From 4732bd1457244ff0a1eb1d86eeebd3120ee14665 Mon Sep 17 00:00:00 2001 From: Jake Bolewski Date: Fri, 4 Sep 2015 02:45:30 -0400 Subject: [PATCH] update CONTRIBUTING documentation now that you cannot really edit the documentation robustly through the web interface --- CONTRIBUTING.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b41fdb565916..84e72a94de8fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,21 +70,7 @@ Coveralls shows functionality that still needs "proof of concept" tests. These a *By contributing documentation to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).* -Julia's documentation is stored in the `doc` directory, and like everything else can be modified using `git`. However, for small changes one can also use GitHub's web interface: - -- Navigate to https://github.com/JuliaLang/julia -- Click `doc` -- If you want to modify an entry in the help for Julia's standard library, click `stdlib` -- Pick the file you want to edit (for example, `base.rst`) -- Select the `master` branch (if not browsing it already) -- Click "Edit" -- Click on the icon that looks like a fullscreen symbol ("Zen" mode) -- Search for the function you want to change -- Make your changes -- Exit Zen mode -- Provide a title -- Provide a longer description of your change with the tag `[av skip]` included at the bottom (this is used in order to prevent the AppVeyor job queue from growing too large because of documentation edits) -- Submit your change +Julia's documentation is stored in the `doc` directory, and like everything else can be modified using `git`. Julia's documentation is built with [Sphinx](http://sphinx-doc.org/contents.html), which supports (and Julia's docs rely heavily on) [ReST directives](http://docutils.sourceforge.net/docs/ref/rst/directives.html). To build the documentation locally, run @@ -96,6 +82,20 @@ or from Julia's root directory. Sometimes errors only show up in one of them, so if you're preparing a pull request it is nice if you've checked both formats before you submit. +Existing docstrings now live primarily in `base/docs/helpdb.jl`. +It is a goal over time to move the docstrings inline to their respective method defintions. +If you want to edit the body of a method docstring, you simply then need to run the `doc/genstdlib.jl` script to regenerate the restructured text files **after** you have already rebuilt Julia. +If you want to edit an existing docstring signature, you **first* have to change the signature in the `doc/stdlib` `..function` or `..data` defnition (not the autogenerated content) and *then* +edit the helpdb.jl or inline method docstrings. The existing signatures in the `doc/stdlib/*.rst` files are patterned matched to base docstrings and the new content overwrites the content in `doc/stdlib/`. +The signature definitions **must** be in sync or else the pattern match will fail and documentation will be lost in the result. +To add entirely new methods to the `stdlib` documentation, first add the signature in the appropriate `rst/stdlib/*.rst` file before writing the docstring, rebuilding Julia, and re-running `doc/genstdlib.jl`. + +It is encouraged to write all new docstrings in Markdown markup. +If you need to write a more complicated docstring that contains cross-references or citations it can be written in a restructured text (RST) codeblock. +Many of the existing docstrings are currently restructured text codeblocks and these will be transitioned to Markdown over time. +RST codeblocks are deliniated with the triple-quote ` ```rst ` Makdown codeblock syntax. +The content of the codeblock is spliced directly into the final restructured text document unmodified. + ### Contributing to core functionality or base libraries *By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).*