On Wed, Jun 26, 2019 at 6:24 PM Stephen Finucane <sfinucan@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/9d4161f955681c83bf121d84f... [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_... [4] 'preamble' in https://www.sphinx-doc.org/en/master/latex.html#the-latex-elements-configura... -- Akihiro Motoki (irc:amotoki)