python-sphinx

问题 At the risk of being told I didn't research this enough (I have been at this for the goodpart of a week now), I can't get the autoclass feature to work in sphinx. I get a range of import errors. I've added both sys.path.insert(0,os.path.abspath('.')) sys.path.insert(0, os.path.abspath('..')) to the conf.py file so that shouldn't be the reason, as I've tried a whole host of other files too. I've made a small example repo here: GitHub But the jist is this: In a repo of the structure: funniest

问题 In my documentation I have an examples directory where I can say, .. literalinclude:: examples/1_basic_usage.py :language: python :linenos: ..which works great, because they're code and they're formatted correctly as code. However, I want to do a literalinclude on non-code documents. At the entire-project level I already have AUTHORS , DESCRIPTION , ATTRIBUTION , etc. defined, and I want to (essentially) paste them in-place but I don't know how. Hopefully it's similar to this NON WORKING

问题 I'm trying to use substitutions in a parsed literal block in my Sphinx documentation like this: <dependency> ... <version>|release|</version> </dependency> Which gets rendered like this: <dependency> ... <version>|release|</version> </dependency> Where what I want is this: <dependency> ... <version>1.7.3</version> </dependency> If I add spaces around the substitution in the source, I get this: <dependency> ... <version> 1.7.3 </version> </dependency> So I know release is defined as I expect.

问题 I am writing a Sphinx documentation for a Python project with a single top-level package my_package . To reference modules/classes in this package, I currently use :mod:`my_package.my_module` :class:`my_package.MyClass` :class:`my_package.my_module.MyOtherClass` These references are then generated as my_package.my_module my_package.MyClass my_package.my_module.MyOtherClass My question is: Is there a way of configuring Sphinx so that I can use shorter references, like :mod:`my_module` :class:

问题 I have a fairly complex project with a fairly large documentation. Converting the normal user guide to PDF with Sphinx via make latexpdf works quite well. However, if I also want to include the library reference with all function, class, and module documentations, the command fails with: ! LaTeX Error: Too deeply nested. Manually reducing the nesting is not an option. Sphinx internally nests parameter descriptions, function descriptions, module descriptions and whatnot. So figuring out in

问题 I am trying to customize the color of the LaTeX inline formula when using Sphinx documentation package, and html output. The details: I have a file called func.rst , which includes the following line: Let :math:`x_{1}` be a binary variable. which is rendered successfully into LaTeX in the documentation I created with Sphinx. (I have 'sphinx.ext.imgmath' listed in extensions in conf.py ) My goal is to have x_{1} colored in red. Things I tried: Adding the color inside the formula: Let :math:`

问题 I'm writing reST documents that will be rendered to HTML and PDF using Sphinx. My source files are UTF-8, and expect my HTML to be displayed as UTF-8. What's the best practice for writing the multiplication sign? That is: ×, not x. I know I can insert it as a Unicode character. If I were writing LaTeX, I'd use \times . In HTML there's × . Is the simple Unicode going to properly survive the conversion process when I render everything with Sphinx? Even if I render to other more exotic formats?

问题 As an extension to this question: how can you add a description under each of the gridded images using Sphinx and reStructuredText? For example, a table, three images across with a caption centered under each image. 回答1: I am not sure if this is possible with just the figure directive, like it is with the image directive. However, whilst horrible to look at, you could wrap the three figures in a table. For example, the following reStructuredText +-----------------------------------------+----

问题 I have a documentation set in Sphinx reST. I've included sphinx.ext.mathjax in conf.py, and included the line "mathjax_path = 'http://cdn.mathjax.org/mathjax/latest/MathJax.js'". I believe that is all I need to do before adding markup to the rst files. But my equations aren't being rendered. For example, :math:`a^2 + b^2 = c^2` comes out of the browser as \(a^2 + b^2 = c^2\) No fancy font or anything. The HTML is <span class="math">\(a^2 + b^2 = c^2\)</span> 回答1: You still need to declare the

问题 Will the Sphinx documentation engine successfully generate documentation on a project that doesn't import well? In particular my project has an exotic dependency. I don't want document generation to depend on this dependency. Does Sphinx need to import my module and use introspection or does it parse? 回答1: If you're using the autodoc extension, then yes, your project must be importable. But sometimes it's possible to mock out dependencies in your conf.py (since, presumably, at the time of