0

I have several projects with one repository per project. One of these repository manages a global documentation, all the others are python packages.

I would like to keep each package documentation independent (not only the module documentation but also installation instruction/examples/etc.). In other words, each package is responsible of its own documentation.

The main documentation repository should include all documentations (and add some structure over it together with some text to link all these packages together). I'm looking for a simpler/cleaner solution than what I have for now.

Current solution

Package documentation

Each package has a doc/ folder, which contains both a module_description.rst (structured autodoc statements). For example, for package_name that would look more or less like this:

Interface
----------

.. autoclass:: package_name.AbstractClass
    :members:
    :undoc-members:
    :member-order: bysource

Basic implementations
---------------------

.. autoclass:: package_name.ImplementationOne
    :members:
    :undoc-members:
    :member-order: bysource

.. autoclass:: package_name.ImplementationTwo
    :members:
    :undoc-members:
    :member-order: bysource

The second file I have is a index.rst which look like:

.. toctree::
    :glob:
    :hidden:
    :maxdepth: 2

    module_description
    tutorials/*
    examples/*

############
Package Name
############

Install instructions
====================

.. code-block:: bash

    pip install package_name

Main doc

The main documentation includes a reference to a document that contains only one line:

.. include:: ../../submodules/package_name/doc/_sources/index.rst

To make this work, as you probably guessed, I used a git submodule that points to package_name repository and allows me to get the file package_name/doc/_sources/index.rst. Doing this alone wont work as the autodoc statements wouldn't find the module package_name.

I therefore need to install the package in the main documentation. I have two options, either I install it from the submodule, or directly from the package registry (both are fine with me).

Question

Can I avoid adding a git submodule and only install package_name? If so, how can I include its doc/index.rst from the main sphinx documentation?

Maybe there is even a better approach, but I can't find any article on this. Any reference would be welcome as I struggle finding the right words to ask my search engine friend.

Note that I have a constraint, I want gitlab to generate pages from this main documentation build.

cglacet
  • 8,873
  • 4
  • 45
  • 60
  • Would [intersphinx](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) do what you need? – Steve Piercy Nov 12 '20 at 03:32
  • I saw that extension but I'm not exactly sure. I think it doesn't fit my needs. From what I understand it can only reference existing documentation (one that has already been built), while in my case I would like to reference raw document (.rst files) without building the referenced documentation. But maybe I miss interpreted that extension documentation. – cglacet Nov 12 '20 at 09:26
  • 1
    You could build the docs for each of the subprojects, then use intersphinx in the super project. Then write in the super ``. It's very much like referring to reST objects. – Steve Piercy Nov 13 '20 at 05:33
  • Oh, that may be an interesting alternative indeed. I would need to look at the details and see what's possible or not. Will it render in the same way as when including from the main documentation? For example will the TOC entries be included in the main doc's TOC? If you have a complete example of this working in the same kind of context don't hesitate to post an answer. That sound like an alternative that is cleaner than what I currently do if it works. Otherwise ill publish my test as an answer but it might not be as good since I don't have experience with this solution. Thanks – cglacet Nov 13 '20 at 11:01
  • 1
    The best I can do is point you to Pyramid's documentation, which refers to both the Python standard library and other projects under the Pylons Project organization. We don't have a super project, but we do have lots of interconnected projects. https://github.com/Pylons/pyramid/blame/a71df99b57e88788cf9ce3a78fc005f309033bbd/docs/quick_tour.rst#L676 and https://github.com/Pylons/pyramid/blame/dbef47bdd0c0f1b719bc442635acb01a66cf8b5f/docs/whatsnew-1.2.rst#L164 are two examples. See toctree entries under https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree – Steve Piercy Nov 14 '20 at 08:00

0 Answers0