Open Stack

On Wed, Jun 26, 2019 at 6:24 PM Stephen Finucane <sfinucan at redhat.com> wrote:
>
> On Mon, 2019-06-24 at 16:36 -0700, Michael Johnson wrote:
> > 4. We should document how to ignore or re-order the docs. We have an
> > internal API reference that comes through as the first section, but is
> > of little use to anyone outside the developers. It is also confusing
> > as the actual Octavia API-REF link doesn't render.
>
> I think this happens because it renders pages in the order that it
> encounters them. If you ensure there's a table of contents on the index
> page of each subsection ('/user', '/admin', '/config', ...), and that
> there's a top-level table of contents linking to each of these from
> your 'master_doc' as defined in 'conf.py (typically 'index') then
> things _should_ render in the correct order. These table of contents
> _could_ be hidden, though I haven't tested that yet.
>
> I plan to rework the nova docs according to the above...as soon as I
> get the darn thing building.

I found time to explore TOC related stuffs a bit deeper for the
neutron document.
I share my experiences below.

BTW, it looks better to prepare some place to share our knowledge, etherpad?

P.S.
I still have a trouble in sample config files (relative paths and
literalinclude),
but it is a different topic. It would be nice if someone can dive into
this topic.


Let's start the detail on TOC.

[TOC structure]

It seems the HTML and LaTeX builders handle toctree in a bit different manners.
The following are what I hit. I noted solutions/workarounds for
individual items,
but another solution is to use a separate top page (See "Separate top
page" below).

The following style like [1] is used commonly in our OpenStack project
documents.
This is useful for HTML documents but it is not for PDF documents :-(

  Installation Guide
  ------------------

  .. toctree::
     :maxdepth: 2

     install/index

leads to the following TOC in a PDF doc. It does not sound nice :p

   1 Installation Guide
       1.1 Networking service Installation Guide
   2 Networking Guide
       2.1 OpenStack Networking Guide

To avoid this, we need to use toctree without sections in the top page.


[Search page]

"search" page works only for HTML pages. It is meaningless in PDF docs.
The straight-forward solution is to use "only" directive.

  .. only:: html

     * :ref:`search`


[URLs in toctree]

> > It is also confusing
> > as the actual Octavia API-REF link doesn't render.

It seems the latex builder does not consider a direct link in toctree
like below.
In case of the neutron doc, I created a new rst file to point the API
reference [2],
but it is just a workaround.

  .. toctree
     :maxdepth: 2

     ...
     API Reference <https://developer.openstack.org/api-ref/network/>
     ...

[Separate top page]

You can also have a separate top page (master_doc) for PDF document [3].
We usually specify a file specified in 'master_doc' (default: 'index')
to 'startdocname' but we can use a different one.

  latex_documents = [
      ('pdf-index', 'neutron.tex', u'Neutron Documentation',
       u'Neutron development team', 'manual'),
  ]


[TOC level]

By default, the first two levels are shown in TOC.
If you would like to show deeper levels, you need to set 'tocdepth'.
To show the fourth level, the following needs to be configured in
doc/source/conf.py [4]
(The number starts from 0, so 3 means the fourth level):

  latex_elements = {
      'preamble': r'\setcounter{tocdepth}{3}',
  }


[Stop generating the index]

It seems the latex builder always tries to generate the module index by default,
but if we do not load all modules in a document the index would be
partial and not useful.
To disable this, the following configuration in doc/source/conf.py would work:

  latex_elements = {
      'makeindex': '',
      'printindex': '',
  }


[1] https://opendev.org/openstack/neutron/blame/commit/9d4161f955681c83bf121d84f1bc335cef758fce/doc/source/index.rst#L37-L44
[2] https://review.opendev.org/#/c/667345/6/doc/source/reference/rest-api.rst
[3] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_documents
[4] 'preamble' in
https://www.sphinx-doc.org/en/master/latex.html#the-latex-elements-configuration-setting

--
Akihiro Motoki (irc:amotoki)