-
Notifications
You must be signed in to change notification settings - Fork 66
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
Choosing documentation syntax; rst vs. md? #49
Comments
Same same but different. I vote rst and numpy documentation style. |
md -> rst : I think we already at a point where almost everything is rst except the api documentation. I already tried the rst parser solution provided by @MichaelHatherly in #4 but this seems to provide the rendering in REPL (symbol ?). I guess we are looking for the save function which generates the documentation files. Options could be that we'd write the functionality in julia (REPL renderer & save function, this would help the community also) or, since we already discussed about sphinx, write a functionality for sphinx to process julia files (already has rst renderer, has to find the docstring from the source files). rst -> md : We're already using Lexicon to create api documention (no worries there) but the notebooks are a bit problematic. Ipython nbconvert has a functionality to generate .md but when me and @ahojukka5 tested it, mkdocs it didn't render them quite well (all code parts we more like one long inline function). Is there any other way/program to convert notebooks? Maybe if we convert notebooks straight to html although this causes a bit friction on the server side when we have to manually move files to correct directories. Sounds more like spaghetti than solution 😆. I vote for rst even if it's a bit more work. |
Ok, I just wanted to double check this. I updated CONTRIBUTING.md. |
We have already discussed this in context of docstrings but I think this needs another verification because this affects to all documentation we making in future. Some of our documents are now rst and some are md. I think we need to choose one and keep on that.
Already known is that
Some links related to this
Do you have any opinions for this? I personally suggest that we use rst in our documentation, mainly because I don't see any good (enough) reasons to use md.
Consequences:
md -> rst : change filename extensions, fix links, find a way to generate api documentation
rst -> md: change filename extensions, change sphinx -> mkdocs in dgs, fix links, find a way to render notebooks
The text was updated successfully, but these errors were encountered: