Sphinx How to cost a page with linked directories

Sphinx Health Cost Page Catalog problem

Use Restructuredtext to write blogs when each blog is a separate page. If you want to use Sphinx for each page of the cost of the table of contents, found a long time to find it seems that Sphinx does not support. There are similar problems on the Internet.

The following are two practical scenarios to discuss the solution.

Single document mode.    In a Sphinx project, it consists of only one document index. Multilevel document mode. In a Sphinx project, there are multiple levels. Assume that the master document for a multilevel document is index. There is also a subdirectory a/b/c in the Sphinx. The a/b/c/master documents are Aindex,bindex,cindex respectively.

One way to solve this problem

Sphinx v1.1.3 After the version, if you create a new project for each blog, it can be indirectly resolved. Assume that the blog file is Index.rst. Include the file yourself in Toctree. Although it will cause Sphinx warning warning, but also can temporarily meet the requirements of the Health cost page.

Directory ================================

.. Toctree::

Index

But this approach does not solve the underlying problem. Because there are several drawbacks to this approach:

Only single document mode is supported. You must create a new project for each blog.    Multi-level document mode causes the entire project to fail to generate HTML because of recursive invocation. Hateful warning remind, red glaring.

So the scheme is just a stopgap. We have to think of other ways. Final Solution

In fact, Sphinx's Official document mentions a solution.

The special entry name self stands for the document containing the Toctree directive. This is useful if your want to generate a ' sitemap ' from the Toctree.

That is to say, Sphinx has taken into account the use of the keyword "self" in the catalog of cost pages.

Directory ================================

.. Toctree::

Self

However, in the actual use will find that self can only produce the title of the cost page, for the other headings of this page, such as the first level, level two headings, do not generate the corresponding link.

Therefore, we should start from the source code to solve. A general understanding of the next Sphinx code, from the sphinx-1.2.1-py2.7.eggsphinxenviroment.py file to find such a function _entries_from_toctree.

def _entries_from_toctree (Toctreenode, parents, Separate=false, Subtree=false):
            "" "Return TOC entries for a toctree node." ""
                refs = [(E[0], e[1]) for E in toctreenode[' entries ']] entries = [] for (title, ref) in refs: Try:refdoc = None if Url_re.match (ref): Refere nce = Nodes.reference (', ', Internal=false, Refuri=ref, Anchorname= ') ', *[nodes. Text (title)]) para = Addnodes.compact_paragraph (",", reference) item = Nodes.list_item (', para) TOC = nodes.bullet_list (', item) elif ref = = ' self '
                        : # ' self ' refers to the document from which this # Toctree originatesref = toctreenode[' parent ' if not title:title = Clean_astext (self.ti
                                                    TLES[REF]) reference = Nodes.reference (', ', Internal=true,
                                                    Refuri=ref, Anchorname= ', *[nodes. Text (title)]) para = Addnodes.compact_paragraph (",", reference) item = Nodes.list_item (', para) # don t show subitems TOC = Nodes.bullet_list (' , item) else:if ref in Parents:self.warn (ref, ' C
                                      Ircular toctree references ' detected, ignoring:%s <-%s '%
                            (Ref, ' <-'. Join (parents)) Continue REfdoc = ref TOC = Self.tocs[ref].deepcopy () self.process_only_nodes (TOC, b Uilder, ref) if title and Toc.children and Len (toc.children) = = 1:chi
                                LD = toc.children[0] for Refnode in Child.traverse (nodes.reference):
                                    If refnode[' refuri '] = = ref and \ Not refnode[' Anchorname ']: Refnode.children = [Nodes. Text (title)] ...