Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Documentation System #8791
A metadata system for global objects + pretty markdown parsing and display (see the readme). For example:
@doc """ ... flowing rivers of technical poetry ... """ -> function foo() ...
Documenting multiple methods of a function will concatenate the doc strings together, in the order the methods were originally defined, and this is overloadable.
Docs can be queried with e.g.
doc(Docs.doc) @doc Docs.doc @doc @doc # For macros @doc text""
(and you can try these out on this branch – the repl help key
I found that it was quite easy to just parse the old helpdb.jl file, put its contents into the new help storage and have the new help-system displaying 99% of what there was before:
I added some really basic documentation examples in basedocs.jl – hope that's OK. It's not meant to be final in any way so much as to get something going, and give people something to try out in the repl (e.g. you can do
I haven't tested it extensively (I'm only using Docile/Lexicon in a subset of my private code tree, basically the stuff that was developed after these packages became available). But everything I've tried so far suggests it's the cat's meow.
Specifically, I was wondering about this for
referenced this pull request
Nov 12, 2014
I only mention
That's only an implementation detail, though – I'm definitely on board with fuzzy searching for docs in general. @MichaelHatherly So you have this to working in Docile/Lexicon already?
Having a more intelligent fuzzy-matcher could be quite nice. Not sure what it would look like though.
added a commit
this pull request
Nov 23, 2014
Pushing forward on completing the transition - it seems that the next step is to transition
Does this mean that our standard library documentation should be translated to Markdown first to leverage the new system best? This may not work best with readthedocs - does it have to use rst?
I think readthedocs requires RST, yes. That said, we already have our own docs template and website, so I'm not sure readthedocs really buys us that much – @MichaelHatherly has done a lot of work on generating great documentation pages and might be interested in helping to move away from it entirely.
OTOH, it wouldn't be hard to generate RST manual pages from the inline docs using Markdown.jl, so that's another option.
The important thing is to have some way to share content between Base docs and the manual – otherwise there'll be a lot of repeated work.