python-sphinx

问题 How can I make an equation in restructured text, that is followed by an equation number: p = f(x) (1) .. math:: p = f(x) would only lead to: p = f(x) 回答1: .. math:: p=f(x) :label: eq:pfx 回答2: Looking at this a few years later, it appears that the number is still not automatically placed on the right of the equations. I'd therefore like to supplement the accepted answer a bit. First you add a label to the equation in the rst file: .. math:: :label: pfx p = f(x) This will generate a <span> of

问题 I'm trying to get my Sphinx documentation build correctly and have cross-references (including those from inherited relations) work right. In my project, I have a situation which is depicted in the example below, which I replicated for convenience on this github repo: $ tree . . ├── a │ ├── b │ │ └── __init__.py │ └── __init__.py ├── conf.py ├── index.rst └── README.md In a.b.__init__ , I declare classes A and B . B inherits from A . In a.__init__ , I import A and B like: from .b import A, B

问题 I'm trying to get my Sphinx documentation build correctly and have cross-references (including those from inherited relations) work right. In my project, I have a situation which is depicted in the example below, which I replicated for convenience on this github repo: $ tree . . ├── a │ ├── b │ │ └── __init__.py │ └── __init__.py ├── conf.py ├── index.rst └── README.md In a.b.__init__ , I declare classes A and B . B inherits from A . In a.__init__ , I import A and B like: from .b import A, B

问题 I'm getting the warning: WARNING: document isn't included in any toctree for files that exist in the document because they've been explicitly included. So I have the index file: .. toctree:: :maxdepth: 2 pages/0010-foo pages/0020-bar In the file 0020-bar.rst, I'm specifically including a number of other files, as in: .. contents:: :local: .. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst But when I build the project, I still get a warning that 0070-baz.rst isn't

问题 I have this problem all the time that I want to write a docstring like this: def foo(arg): '''Add ``arg`` to the list of :class:`foo.bar.baz.Argument`s.''' pass However, that doesn't work, Sphinx will warn that py:class reference target not found: foo.bar.baz.Argument`s so it's treating the s after the closing backtick as part of the class name. This does not happen with e.g. punctuation marks like the dot . . Is there anything to be done about this, except adding a space between the class

问题 I'm trying to automatically build the class inheritance tree of the raytracing module (available on pip) with automodapi extension for sphinx , however, there is one class I would like to omit. The automodapi allows the creation of the tree with the command .. automod-diagram:: moduleName and in the doc there seem to be a skip method, but it only skips in the documentation generation, as I want to skip an object in the class diagram. The name of the class I want to omit is Materials . To

问题 I'm trying to automatically build the class inheritance tree of the raytracing module (available on pip) with automodapi extension for sphinx , however, there is one class I would like to omit. The automodapi allows the creation of the tree with the command .. automod-diagram:: moduleName and in the doc there seem to be a skip method, but it only skips in the documentation generation, as I want to skip an object in the class diagram. The name of the class I want to omit is Materials . To

问题 Sphinx-autodoc flattens dicts, lists, and tuples - making long ones barely readable. Pretty-print format isn't always desired either, as some nested containers are better kept flattened than columned. Is there a way to display iterables as typed in source code? 回答1: Get it straight from source, and add an .rst command for it: # conf.py from importlib import import_module from docutils import nodes from sphinx import addnodes from inspect import getsource from docutils.parsers.rst import

问题 Sphinx-autodoc flattens dicts, lists, and tuples - making long ones barely readable. Pretty-print format isn't always desired either, as some nested containers are better kept flattened than columned. Is there a way to display iterables as typed in source code? 回答1: Get it straight from source, and add an .rst command for it: # conf.py from importlib import import_module from docutils import nodes from sphinx import addnodes from inspect import getsource from docutils.parsers.rst import

问题 I'm developing documentation in Sphinx, and would like to separate sections in my table of contents using horizontal bars. I often see this in menus: Is there a way to do it in sphinx? 回答1: The python sphinx .. toctree:: directive doesn't allow much variation besides the documents you include in the directive body, plus a few directive options. What I've seen others do in this case is splitting one toctree into several, including reStructuredText in between them. You could use an alternative