-
-
Notifications
You must be signed in to change notification settings - Fork 5.5k
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
WIP: Doc Transition #11828
Conversation
Could we just store them as plain text rather than |
@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. |
@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. |
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. |
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 :) |
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. |
cf2c4ff
to
db6eccf
Compare
b95f63f
to
70a360a
Compare
5f23f9e
to
5e375cd
Compare
fe1bd3f
to
a079cd2
Compare
b806ec8
to
af429c2
Compare
@@ -0,0 +1,80 @@ | |||
using .Markdown |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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
b23c4b3
to
a100499
Compare
Superseded by #11906. |
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. |
Yeah it's totally doable, just needs implementing. |
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:
["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"]
– need to implement docs for variable bindings to fix this.On the whole though we should only have lost on the order of tens of docstrings, as opposed to thousands.