Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Doc Transition #11828

Closed
wants to merge 27 commits into from
Closed

WIP: Doc Transition #11828

wants to merge 27 commits into from

Conversation

MikeInnes
Copy link
Member

This moves our 1503 docstrings from helpdb.jl into the new doc system. Docstrings are now stored in base/docs/helpdb.jl (soon to be scattered around base) and we have a hackish script which dumps those docstrings into the RST manual (at least until we move to markdown).

Caveats:

  • Undocumented globals: ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"] – need to implement docs for variable bindings to fix this.
  • helpdb didn't support multimethods well, so some functions and docstrings have duplicated entries.

On the whole though we should only have lost on the order of tens of docstrings, as opposed to thousands.

@tkelman tkelman added the docs This change adds or pertains to documentation label Jun 23, 2015
@MichaelHatherly
Copy link
Member

unless you really hate blue

Could we just store them as plain text rather than MD objects?

@ViralBShah
Copy link
Member

@MichaelHatherly Are you coming to JuliaCon? Would be great to sort this all out in person in case you are planning to be at MIT.

@MichaelHatherly
Copy link
Member

@ViralBShah unfortunately I live many, many timezones away :( I'd have loved to be there though. I should be around for most of tomorrow so will be able to follow along.

@MikeInnes
Copy link
Member Author

Could we just store them as plain text rather than MD objects?

Technically yes, although there's a risk of setting the precedent of plain text docs in Base being acceptable. This way it's obvious that the RST docs are a work in progress, which might be a good thing.

@MichaelHatherly
Copy link
Member

risk of setting the precedent of plain text docs in Base being acceptable

Hopefully not if potential additions are reviewed, but I'm not particularly bothered about blue text for a little while – might make things move a bit faster :)

@hayd
Copy link
Member

hayd commented Jun 24, 2015

I had a branch which did the rst to md conversion (or pretty close) to something like https://gist.github.com/hayd/9cbd69e5e85693d1f6eb

I think it's this: hayd@246314b

Uses pycall/pypandoc to convert the rst docstrings to markdown, they need a little manual tweaking but pypandoc does a pretty good job.

@@ -0,0 +1,80 @@
using .Markdown
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is missing a header, as well as using 2 space indentation (rather than 4).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


.. function:: eye(A)

Constructs an identity matrix of the same dimensions and type as ``A``.
Constructs an identity matrix of the same dimensions and type as
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This appears to be missing the remainder of the line (after a ``... not sure if what's the pattern, but there's quite a few lines below which demonstrate similar - the diff should definitely be combed through).

Also this (function eye(A)) now appears three times as the same signature :s

@StefanKarpinski
Copy link
Member

Superseded by #11906.

@Ismael-VC
Copy link
Contributor

Undocumented globals: ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"] – need to implement docs for variable bindings to fix this.

One of the few things I liked about .NET when I was forced to use Visual Studio (and that now I miss in when I'm forced to use XCode 😁 ) was the ability to document global variables:

/// <summary>
/// Always use this
/// </summary>
List<string> my_list = List<string>();

Could we do something like this work?

"Returns the number of available CPU cores."
global CPU_CORES

function init_sysinfo()
    # set CPU core count
    global const CPU_CORES =
        haskey(ENV,"JULIA_CPU_CORES") ? parse(Int,ENV["JULIA_CPU_CORES"]) :
                                        Int(ccall(:jl_cpu_cores, Int32, ()))
    global const SC_CLK_TCK = ccall(:jl_SC_CLK_TCK, Clong, ())
    global const cpu_name = ccall(:jl_get_cpu_name, ByteString, ())
end
help?> CPU_CORES
...
Returns the number of available CPU cores.

@MikeInnes
Copy link
Member Author

Yeah it's totally doable, just needs implementing.

@StefanKarpinski StefanKarpinski deleted the doc-transition branch June 29, 2015 02:04
This was referenced Jun 29, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants