I documented some modules of a Python package I wrote using NumPy style, and I set up a readthedocs website to host the automatically generated documentation (with sphinx.ext.napoleon). Despite trying to follow the NumPy documentation style guidelines, the rendered docstrings don't appear to have the same appearance as NumPy's own documentation, which looks clearer to me. (I'm not talking about the overall html theme, but how the parameters and class methods are displayed)
My conf.py file and all .rsts of the documentation can be found in the repo. I also use nbsphinx and nbsphinx-link to render a Python Jupyter notebook, but I hope this doesn't interfere with napoleon/autodoc. I think that using numpydoc instead of sphinx.ext.napoleon isn't an option because of using nbsphinx. Also, if I'm not mistaken, using napoleon should be equivalent to using numpydoc.
How NumPy's documentation shows the parameters of a class:
How my docs shows the parameters of a class, even though I wrote the docstrings following NumPy's docs style and use sphinx.ext.napoleon with napoleon_google_docstring = False in conf.py. (Notice the dotted list, how the description of the parameter is following the name and default values in the same line...)
Related
I have a docstring in the beginning of every module describing its usage and functionality. Here I also want to add the most relevant parameters - like settings in a parameter file or via command line arguments. It's no classical function parameters since the module might be called as stand-alone as well (via if __name__ == '__main__' capture). But since the ordinary parameter formatting of Sphinx is neat I want to just re-use it.
However, Sphinx seems to handle the "Parameter" section differently when in a module compared to when in a function.
This is how they are formatted differently:
Parameters in function docstring:
Parameters in module docstring:
You see the difference. In functions the keyword "Parameters" is added and then we have a nice bullet list. In modules no title is created, no list, the type is not set in braces but on an additional line etc.
Docstring format is the same (numpydoc):
Parameters
----------
pars : dict
Parameter dictionary.
key : str
Parameter name.
vs.
Parameters
----------
num_axial_segments : int
The number of axial rotor segments.
magnet_segmentation_method : int
The method of magnet segmentation.
0: Uniform segmentation (all magnets same amount of segments).
Does anyone have an idea why it's handled like this? And what I can do about it?
I would like the parameters in modules output in the same way as in functions.
The style used to render the docstring sections is dependent on the HTML theme you are using with Sphinx.
Does anyone have an idea why it's handled like this?
The reason the styles are different for module and function docstrings, is because it's customary to use a command-line syntax style to document scripts that is different from function signature syntax style . Notice the style you showed for the module docstring is similar to a list of command-line arguments.
I would like the parameters in modules output in the same way as in functions.
Different themes may render module docstrings similarly or differently from function and classe docstrings. You would have to choose a different theme or customize the theme's CSS by copying the style used for functions to the style used for module docstrings.
the type is not set in braces but on an additional line etc.
This is noteworthy because you would expect the napoleon-sphinx extension to not render type and name on different lines as if it were using classic reST syntax instead of Google style or Numpy.
I would recommend trying a different HTML theme or setting the napoleon_use_param , napoleon_use_ivar and napoleon_use_rtype explicitly to see if there's a difference.
And what I can do about it?
The examples given for Google style or Numpy style suggest using docstring sections but that's somewhat oversimplified because command-line style syntax is better illustrated and automated by the way argparse implements it. There are a few extensions meant to ease and automate the process of documenting scripts.
As for the difference in style I wouldn't worry about it (admittedly in the HTML theme you are currently using it doesn't look very good). A command-line invocation of a script or a run-time call of a function are different and accordingly themes may and will render those docstrings sections with visual differences.
I have I small module that I use inside one of my projects. Now I decided to place it on github so now I am writing some docstrings and cleaning the code.
I have a composition of 2 classes so the initialization looks like this:
foo = Class_1()
bar = Class_2(param1=foo)
I know that the first argument to the Class_2 has to be an instance of Class_1 or the code won't work. But it may be clear only for me as I wrote code of Class_2, but when using module as API it may be unclear for a user that param1 has to be an instance of Class_1. If someone will use bar = Class_2(param1='foo'). The trackback will be bad and it will be impossible to understand what happened. So the question is: do I need to check in my __init__ that isinstance(param1, Class_1) and if no raise an excaption with an appropriate message, or writing good documentation is enough?
This is very opinion-based (not great for StackOverflow in particular) - but in my opinion, you should do both.
On the one hand, using isinstance() and exception-handling are both good defensive-coding practices.
On the other hand, inline documentation is nice. Per the Python developer guide:
The markup used for the Python documentation is reStructuredText, developed by the docutils project, amended by custom directives and using a toolset named Sphinx to post-process the HTML output.
Some IDEs, such as JetBrains PyCharm, are configured to automatically pick up well-formed reST docstrings and perform automated type-checking based on those conventions (which I've found to be really useful). See also: PEP 257 and What is the standard Python docstring format? for details.
I'm using pelican in Python to generate the static pages. It is fine to use markdown with Pygment to highlight a code block, however when it comes to the inline highlight, there is a significant difference.
Please check my page. The page is in a dark background, but the inline highlight with the back ticks `` are white background.
The markdown code is
To clearify what exactly the command returns,
one can use `pack('>i', -2500).encode('hex')`{.python}.
Or I have a more complex solution like, `''.join(r'\x%02X'
% ord(ch) for ch in src)`{.python}.
So the question here is how to define the inline highlight style?
I tried to altered the pygments default.css file in the pelican theme, but it didn't work.
I found some related links:
Inline code syntax highlighting in GitHub markdown?
Inline code highlighting in reStructuredText
Pelican uses Python-Markdown with the CodeHilite Extension to pass code blocks to Pygments. Note that code blocks do not include inline code snippets. In fact I am not aware of any Markdown parser which supports highlighting inline code. Generally, inline code snippets are too short to effectively highlight and almost always too short to take advantage of Pygments' language guessing algorithm.
I see you have attempted to inform Markdown of the language using the Attribute List Extension. However, all that does is add a class to the HTML <code> tag that wraps the code snippet. As the CodeHilite Extension only works on blocks, it never even looks at it, and certainly never passes it to Pygments.
There are a few different options you have available (each increasing in the amount of work required):
You can write your own CSS which changes the background and text color so that they match the blocks. You won't get syntax highlighting, but the inline code snippets will at least match your theme. No need to define the language here.
You could use a JavaScript code highlighting library to highlight all the code snippets based on the language you define with the Attribute List Extension. However, this may require you to redefine the CSS for the JS library so it matches the output of Pygments.
You could write your own Python-Markdown extension (or perhaps fork CodeHilite) which also highlights inline code snippets in addition to blocks.
Personally, I would recommend (1) above. In fact, looking at your page, is appears that the code blocks have the following defined:
.highlight pre, .highlighttable pre {
background: #272822;
color: #f8f8f2;
}
That is, a <pre> element with a parent assigned the "highlight" class (or the "highlighttable" class) will be displayed with those colors. As you want the same colors assigned to inline code, add the following rule:
code {
background: #272822;
color: #f8f8f2;
}
Just be sure that you define that after the styles defined by the Pelican theme (which appears to be in http://vfxware.com/theme/css/bootstrap.slate.min.css).
Sure, you could alter the existing CSS, but then if you later decide to update to a newer version of the theme or change themes entirely, you might have to redefine your own rules. Therefore, I like to define my own set of overrides in a separate file which I always make sure is the last one loaded.
I've been bitten by this all too often. My problem was that I was using an older template's old pygment.css file while upgrading the Pygment modules (CSS didn't catch up with the Pygment plugin.
In my case, the older Pygment CSS was using an HTML tag class highlight when it should be using the newer codehilite class name that newer Pygment code is now using. (Thanks to Firefox->Windows->Web Developer->Toggle menu option for pointing out this "breakage".
Replacing the pygments.css CSS-style file does the trick in restoring this much needed code syntax highlighting capability.
To regenerate the pygments.css file, execute:
pygmentize -S default -f html -a .codehilite > pygments.css
or for a darker theme, use Pygmentize monokai style, as listed in pygmentize -L:
pygmentize -S monokai -f html -a .codehilite > pygments.css
Again, problem was that Pygments changed its HTTP tag class to a newer codehilite from an older highlight.
I was wondering if it is possible to use POD(plain old documentation) with Python? And how should I do it?
There does not appear to be a directly supported way to use POD inline in a Python file. However, Python modules (including the Python standard library) are documented using reStructuredText. This is usually done using Sphinx, which produces documentation from reStructuredText-formatted docstrings. Sphinx and rst were specifically designed to fill a similar niche to POD.
Yes. Use '''.
#!/usr/bin/python3
'''
=pod
=head1 NAME
...
=cut
'''
import sys
I couldn't find a documentation about this function...
I specifically want to know what the parameters are and what do the parameters exactly represent...
using python 3
The convention in Python is to use a single leading _ for non-public methods and instance variables. So, _siftdown is not intended to be called externally and, thus, is not documented in the standard library documentation. If you want to examine how it works, look at the code. Note that the latest Python 3.2 documentation now includes links to the source code; see the link near the top of the page here.