sphinx: document data in python without displaying the data

Question

i know i can document (module) constants in sphinx with either

#: a tuple of primes
primes = (2, 3, 5, 7, 11, 13, 17)

or

primes =  (2, 3, 5, 7, 11, 13, 17)
"""a tuple of primes"""

which will then appear in the sphinx generated documentation; i.e. it will look something like this:

somemodule.primes

= (2, 3, 5, 7, 11, 13, 17)

a tuple of primes

but what if the data is a very long list? then i would like to be able to have a docstring in the documentation but not have the actual data itself in the doc.

this is what i would like to have in the doc:

somemodule.primes

a tuple of primes

is there a way i can achieve this?

for completeness:

i ran sphinx-quickstart and enabled autodoc:

autodoc: automatically insert docstrings from modules (y/n) [n]: y

the only thing i have added to index.rst is:

``somemodule``
**************

.. automodule:: somemodule
    :members:

and somemodule.py contains this:

#: a tuple of primes
primes = (2, 3, 5, 7, 11, 13, 17)

then i adapted sys.path in conf.py such that somemodule.py is in that path.

I'm not a sphinx expert, but I don't think sphinx is directly responsible for this - you're likely using the autodoc extension to generate your documentation, correct? — Aran-Fey, Sep 02 '19 at 07:27
yes, the extension `sphinx.ext.autodoc` is enabled; and i use `.. automodule::` for said module. — hiro protagonist, Sep 02 '19 at 07:28
The [`autodata`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autodata) directive accepts an `:annotation:` option that lets you hide the constant's value. I don't know if `automodule` respects that setting if you set it in [`autodoc_default_options`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options`) (and if it does, it'll then apply to *all* constants), but perhaps that's worth a try. — Aran-Fey, Sep 02 '19 at 07:37
i am looking into `autodata` with mixed success so far. if i only have an annotation (and no docstring) i seem to get the annotation plus the `tuple` docstring: `tuple() -> empty tuple tuple(iterable) -> tuple initialized from iterable’s items If the argument is a tuple, the return value is the same object. ` — hiro protagonist, Sep 02 '19 at 08:00

score 5 · Accepted Answer · edited Sep 21 '21 at 12:06

5

Just in case somebody ends up here. To hide the contents of a variable use the meta info list field.

Example:

primes = (2, 3, 5, 7, 11, 13, 17)
"""A tuple of primes.

   :meta hide-value:
"""

edited Sep 21 '21 at 12:06

Alex Waygood

6,304
3
24
46

answered Jun 16 '21 at 09:21

JuanPi

789
1
6
19

great! thanks! haven't tested it yet but it looks as if ti was made for the job! – hiro protagonist Jun 16 '21 at 09:58
2

In my hands, this only worked if I omitted whitespace before the directive - as shown above, the `:meta hide-value:` didn't work, but if I removed the leading spaces between the newline and `:meta` then it worked fine. Using sphinx 3.5.4 here. – J. Lerman Jul 07 '21 at 01:59
2

This also gets picked up from `#:` comments before the variable. – Yelonek Sep 21 '21 at 09:55
This only works with Sphinx 3.5.0 and newer. Ubuntu 18.04 comes with 1.6 and 20.04 comes with 1.8, so there you're out of luck with the distributed sphinx. You can of course install newer sphinx via pip, but that may break other parts of your system. – Martin Pecka Sep 20 '22 at 18:29
@MartinPecka you are not stuck with distro version, just create a virtual environment with venv (or whatever other venv tool you like) and install the latest version of all packages. – JuanPi Sep 21 '22 at 19:43
@JuanPi Not in case I need the docs to be built by a buildfarm over which I have no control... Using distribution versions of packages is a must if you want to build publicly distributable packages via official distro channels. – Martin Pecka Sep 21 '22 at 21:22
@MartinPecka that scenario has nothing to do with your previous comment. There are always constrained scenarios. Anyways publicly distributing packages can be done with way less restrictive scenarios than the one you describe. And, documentation building is more on the side of development, so, in the worst case, build the docs locally with any sphinx you need and upload the tar.gz or zip file to the online service to be added to the package – JuanPi Sep 23 '22 at 06:35
Also, any official distribution of python will have venv with it and you can the create virtual env in within the distro, there are very few cases in which you do not have that power. Read up on venv – JuanPi Sep 23 '22 at 06:37

score 1 · Answer 2 · answered Sep 02 '19 at 08:37

i ended not having any documentation for somemodule.primes in somemodule.py (which makes sphinx ignore it) and putting a manual documentation into index.rst

``somemodule``
**************

.. automodule:: somemodule
    :members:

.. py:data:: somemodule.primes

    a tuple of primes

so far i found no way doing something similar directly in somemodule.py.

sphinx: document data in python without displaying the data

2 Answers2

Linked