On Sunday, March 24, 2019 at 12:21:43 PM UTC-7, Chaman Agrawal wrote: > > I was trying to contribute through a ticket related to documentation but I > am not sure how docstrings are generating HTML and have doubts. > 1) It is ignoring all the function of with names like __function_name__ > and _function_name_. So for such functions, is the documentation in the > code meant only for developers to understand? or can we build it also. > 2) A line in the documentation should have less than 72 characters so in > the 72 characters do we count the indentation spaces also? Also, some > Example and Test docs are not following this, so is this rule not for them? >
Most of the first question is answered in the Sage developer's guide: http://doc.sagemath.org/html/en/developer/coding_basics.html#private-functions. Most of the second question is, too: http://doc.sagemath.org/html/en/developer/coding_basics.html#sage-documentation-style The limit is 80 characters, not 72, and it does include the leading spaces. Sometimes it is inconvenient to break lines in example or test blocks, so we make exceptions. Probably every rule for Sage development has exceptions made for it in some circumstances, but there should be a good reason to make the exception. As far as how it is actually converted to html, that is done by Sphinx: https://www.sphinx-doc.org/ via the command "sage --docbuild reference html". Run "sage --docbuild --help" for some help; you will see for example "-u, --underscore include variables prefixed with '_' in reference manual; may be slow, may fail for PDF output", so if you want to try building the documentation for __function_name__, you can do it, but it's turned off by default. -- John -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
