new doc city #11906
new doc city #11906
Conversation
Current doc generation process generates a ReStructured text format
helpdb.jl file that is loaded when building Julia. The new doc system
will grab docstrings while building Julia and use those to generate
parts of the manual -- currently in ReStructured text, but in the
future in Markdown format.
As a step towards that, this script generates the new Markdown index
from the old ReStructured text index. You can run it as:
julia doc/newdoc.jl
julia doc/markdown.jl
mv base/docs/helpdb{2,}.jl
julia doc/coalesce.jl
The next piece of the doc up date is a script that uses help info
picked up from base/docs/helpdb.jl while building julia, to make a
new standard library. Currently, we merge the docs for all methods
into a single blob which gets included at every point where *any*
method of the function was documented previously. This is a bit
confusing but isn't the end of the world while we migrate to a new
way of generating our manual. The script can be run as:
julia doc/genstdlib.jl
From this, you can do
make -C doc helpdb.jl
This regenerates the old help index from the new generated manual,
allowing you to compare them. The diff is essentially all additions
so we didn't delete any essential documentation.
StefanKarpinski
force-pushed
the
sk/new-doc-city
branch
from
85586e8 to
156e995
Compare
StefanKarpinski
force-pushed
the
sk/new-doc-city
branch
from
156e995 to
eeda20a
Compare
StefanKarpinski
force-pushed
the
sk/new-doc-city
branch
from
eeda20a to
f7f82f6
Compare
|
broken on windows, will see if I can fix it before it claims too many pr's |
| issig(md) = isa(md, Markdown.Code) && length(split(md.code, "\n")) == 1 | ||
|
|
||
| function splitsig(md) | ||
| md = flatten(md) |
There was a problem hiding this comment.
still nonstandard formatting on this file
|
temporary fix for windows in fb10927 This broke inline code quoting, cross-references, and tables. And there was some major data loss in |
StefanKarpinski
added
docsystem
|
@tkelman, thanks for the careful review of this ridiculously large patch. What's the nature of the breakage on Windows? Maybe @one-more-minute or I can help fix it. |
|
|
|
Ah, got it. That actually seems like a fine fix to me. No harm having the constants defined on all platforms. |
|
Are you using |
|
Unfortunately that was due to the help system which produced the original helpdb.jl. There's not much we can do about this automatically, I don't think, but it won't be any worse than it was before at least. |
|
@one-more-minute Before I was able to convert from rst to markdown and these code blocks parsed perfectly (using pypandoc). Does this mean that's no longer possible? or is this only in the generated rsts? (I'm a little confused at what's now generated tbh). |
|
The |
|
My question is not so much about readability, but later converting to markdown ```... I'd already done some work doing this automatically so I confused why this bit's an issue (rst -> markdown). The other question is what (else) has been lost in this... though it's already merged :/ |
|
Skim through and see if you can catch anything I missed. I think linalg was the only doc file that github wouldn't show the diff on, I had to look at that locally. |
| .. function:: eye(A) | ||
| :: | ||
|
|
||
| eye(A) |
|
I'm really displeased that this was merged so soon without the opportunity of proper reviewing. We would never have merged a PR that touched so much code without scrutiny, and the fact that this was merged with so many formatting issues speaks volumes about the second-class nature of documentation in this project. |
|
Once I've fixed this stuff tomorrow I'll put up the diff from the original docs and make sure everyone's happy with the overall changes. |
|
The documentation for eigs and svds is also all fucked up. The |
|
Honestly I feel that the hasty merger of this PR is a giant slap in the face for all the people who have put effort into writing the docs. |
|
I don't think the choice of language is appropriate, however upset you may be. Also, it is just git and everything can be reverted or regenerated. |
|
I stand by my comments, no matter what tone you choose to read from them. I put in a lot of the information that was broken or lost. I warned people that it was easy to lose this information. Then it all happened anyway. But now that the bulk of this PR has been reverted, I shan't say any more. |
|
It's also worth mentioning that this PR was a rebase (?) of #11828, which still had some unaddressed comments on the diff (e.g. eye being repeated) that remained unaddressed here. |
The epic transition from old doc system to new.