How to Remove Bullets from Numbered Toctree in Restructured Text

Managing Sphinx toctrees combined with inline sections

The section headings hierarchy is simply the order as encountered. So your ==== underline sets the title ("H1") and ++++ underline sets the subtitle ("H2") for this page only. Depending what layout you're after...

A. Maybe you wanted a "Table of contents" section as a sibling of the "Overview" section (both within "Thingamajigs" parent), so insert a new H2 section heading:

Thingamajigs
============

Overview
++++++++

Thingamajigs are fun

Table of contents
+++++++++++++++++

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz
    

B. Or maybe you don't want "Overview" in the section headings hierarchy at all, so highlight it by a different means:

Thingamajigs
============

.. admonition:: Overview

    Thingamajigs are fun

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz
    

C. Or list the headings hierarchy within this page, separately from external pages:

.. contents:: In this page
    :local:

.. beware, that contents directive must appear before any heading hierarchy

Thingamajigs
============

.. toctree::
    :maxdepth: 2
    :caption: In other pages
    
    foo
    bar
    baz
    

D. Or do exactly what your last example showed: move the "Overview" content out to a separate ReST document and include its name in the toctree directive body.

Parent element of nested list is bold?

Your reStructuredText mark-up

#. aaaa
#. bbbb
    1. b1
    2. b2

is not correct. As it stands it gets interpreted as a definition list.

To get the expected output you need to insert an extra blank line and also to fix the indentation of the secondary list items. Like this:

#. aaaa
#. bbbb

   1. b1
   2. b2

How to reference another page in project with section ID?

I don't think it's a good approach to use intersphinx if your aim is cross-referencing your project internally.

At this point it has to be noticed: When using one of the autodoc directives like automodule or autoclass, that Python object is placed in the Sphinx index and can be cross-referenced.

But this raises a question: How to cross-reference ReST sections? It's considered an arbitrary location because they aren't objects, and they aren't inserted in the Sphinx index by the autodoc directives (or through a py domain declaration in your .rst).

Well, in that case there are 4 main options to consider (the last may be the least obvious, and thus the most important):

1. Use a ReST hyperlink targets directly above the section.
2. Use Python domain reference directly to the autodoc directive below the section.
3. Use a cross-reference to the document if the section sits on the top of the .rstfile.

Last but not least:

4. Consider you have 1 .rst file that documents one or several packages (lets say your_package.utils). Normal ReST rules have you place 1 section on the top of the file. But there isn't an automodule directive because, probably, the package is an empty __init__.py without a docstring...So what's the best solution in that case?

*****************
your_package.UTIL
*****************

.. py:module:: your_package.UTIL

Modules
=======

(...the usual stuff...)

OK!!! Now, by explicitly declaring your_package.util at above or below the ReST section as a Python module (or any Python object that may apply) what happens??? It gets inserted in the Sphinx index!!! Why is that important?? Because you can cross-reference it as a Python module (packages are, after all, modules) and don't have to cross-reference it as a document, or as a section. Which gives overall consistency to your documentation, index, and cross-referencing...

End result? You never see HTML or anchors..!! Sphinx manages/generates/indexes all of that for you. And that's what you really want. A complete abstraction layer.

Some people would raise objections:

• "You are putting Sphinx/ReST inside your Python docstrings (people don't know how to read that)."

Easily solved, put the plain English in the Docstring and ReST/Sphinx syntax in the .rst files (autodoc will join the parts).

• Others would object:"I want HTML in my ReST!"

Sure enough, but whenever you edit or refactor something it's doomed to become a pain. And who said normal Python/ReST developers looking at your stuff know anything -or want to look at- HTML or anchors?

So the soundest separation goes along these lines.

About using duplicate target names:

There's no real reason to use duplicate target names. A refactor done from your IDE is better served by unique target names. If you decide to move the ReST section the target above simply goes with it.

.. _this_section_without_duplicate_name:

*****************
Your ReST section
*****************

:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`

No anchors needed. Much cleaner and slick.

---

Related Topics