I am building my documentation with Sphinx, to use with readthedocs.io. So far this always worked well. I'm orienting myself at the (in my opinion) excellent documentation of the godot engine.
Since I appreciated the titles in the documentation of the godot documentation, I tried to replicate these, by first having a look at the way they did it. Here's the link to the source for their index file. (Note: the relevant section is at the end of the document)
This seemed reasonable, as they used multiple toctrees, to give every toctree a caption.
When I do the same however, sphinx seems to automatically number my sections, something I do not want. The toctrees do not contain the :numbered: tag.
Here's a code sample, explaining how my toctrees are structured in principle:
.. toctree::
:caption: Section 1
Entry1
Entry2
.. toctree::
:caption: Section 2
Entry2
The expected result would be similar to the godot documentation, with sections having titles but no numbers. Instead I am getting numbers, which seem arbitrary to me:
Section1
1.Entry1
2.Entry2
Section2
1.Entry1
I can't find anything in the godot documentation explaining why they do not have these numbers, and I can't find any mention of it in the Sphinx toctree documentation either.
Any help or pointers towards help are greatly appreciated, thank you for your time.
Edit:
Uploading the repo, with the built static html files to readthedocs.io seems to remove/fix the numbering. It persists in the local built though (the index.html file I built with sphinx in the first place).
The answer to the question, courtesy of mzjn (see comment thread):
A rebuild of the project solved the issue. This can be done by entering
make clean html
in the console, fixing the weird numbering issue.
The relevant github issue can be found here.
This may possibly be caused by sphinx trying to find changes in the code and update these, instead of rebuilding the project every time. In this instance it did not update the toctree correctly.
Related
So I either just have no understanding of how links are supposed to work in Sphinx (despite reading all the documentation I can find) or something very funky is going on.
Firstly, as I understand it, targets must be globally unique in a project so that they can be referenced from anywhere. However, I am able to create explicit targets on two different pages with the same label and I do not get any warnings or errors when building the docs. Instead, one of the targets just seems to take precedence over the other.
Contents of page-1.rst
.. _abc:
Some content...
Now here's a :ref:`reference to content <abc>`.
Contents of page-2.rst
.. _abc:
Some different content...
Building this produces no warnings or errors. The reference links to the target on page-1.rst. Based on my understanding, I'd expect this to warn me about duplicate targets defined across the project. The same thing happens if I move the target (but keep the reference) from page-1.rst to, say, page-3.rst. No warnings, but in this case page-3.rst takes precedence for some reason. Why am I not getting warned about these duplicate targets? I have pretty vanilla configuration, and I've disabled any extensions when checking this functionality.
Additionally, I've found that external link targets don't seem to work with the ref role, but I don't really understand why, and I can't find any information about this. The use case is wanting to reference the same external URL in two separate pages. I understand there is some additional configuration I can do set up a base url and use that in multiple places, but this seems more complicated than what I'm looking for. Basically, why can't I do something like this:
Contents of page-1.rst
.. _abc: https://example.com
Contents of page-2.rst
You really ought to visit :ref:`this place <abc>`.
Building this results in
WARNING: undefined label: abc
Ultimately, these are just things that feel like they go against my intuition based on what I've learned, but I'm starting to wonder if I'm fundamentally misunderstanding something. Any insight would be greatly appreciated!
I'm documenting my Python classes using Sphinx, and sometimes I want to give my parameters quite long descriptions to explain something in details. Unfortunately, Sphinx generates ugly output for me which wastes a lot of space and breaks the whole page appearance:
It can be seen that Sphinx creates a table, then puts "Parameters" header to the left cell, and the actual list of parameters to the right cell. But there should be way to avoid creating this table completely. After playing with the page DOM tree I finally can show that I want to achieve:
Is there a built-in way to do this or I'd have to create a PR to Sphinx theme or Sphinx itself?
After posting an issue to Sphinx bug-tracker and having no response, I've decided to roll-out my own solution (better say, hack). To achieve the look I want, I have written a simple Sphinx extension which post-processes generated HTML code. It can be found on PyPI:
https://pypi.python.org/pypi/sphinxcontrib.divparams
https://pythonhosted.org/sphinxcontrib.divparams/
This doesn't seem to be the best way to solve the issue, but the behaviour I wanted to change is deeply hard-coded in docutils, not Sphinx.
I'm working on a documentation of an Python wrapper around a PyObjC application with Sphinx.
Sphinx adds a confusing and unwanted library description of the library code to this class's property description that happens to be code (please see screenshot, second last line).
How to get rid of it? I looked into conf.py, but couldn't find anything.
Also, I learned, autodoc adds more docstring stuff, but I never asked for it and and can't find whether this is what's even happening and how to turn it off.
The corresponding sphinx code is simply this:
Properties
.. autosummary::
name
code
automatic
We are planning on creating a user manual for our software project. Currently, everything related to the code is documented in Sphinx, and we would like to use Sphinx for the manual.
Since we are writing scientific/engineering software, there will be a lot of topics on things like stress, strain, numerical algorithms, etc. For each topic, we will have a few stages of information:
Basic information: This one or two sentence description can be used anywhere we need a short summary of the topic. Example: simple definition of mechanical stress.
More detailed description: This one paragraph explanation can be used as the opening to a help page, or a summary in a more detailed listing of topics. Example, a paragraph about mechanical stress introducing the equation for axial stress.
Technical information. This can be multiple paragraphs on how the topic applies to the problems encountered by users of our software.
Code information. This will be documentation related to where the topic is encountered in the code. For example, we can point to our implementation of a certain numerical algorithm. We can use sphinx-apidoc like we currently do.
As you can see, the information gradually gets more complex. We would like to manage each topic in their own .rst file, and get the required information as needed. For example, maybe we want to use the basic information section in a tooltip. In the actual help menu, we can use the detailed description in a table of contents on a certain class of topics. In the full article on the topic, like what would be present in a full pdf manual, we can present the technical information along with the basic and more detailed descriptions. Lastly, we would like to keep code information only in our internal documentation.
It would be nice to keep all of the information for a single topic in one file, but to conditionally compile different sections based on the documentation we are generating.
Is there a built-in way to do something like this in Sphinx? If someone is doing something similar, can you tell us about it and give us some highlights of your workflow?
In past I wanted to compile two docs, a public and a private but I didn't want to split my source file (rst).
First step I found the only directive and I thought it was the solution. But when I wanted a entire full rst file in just public or private documentation I can't without indent the whole file.
So I write my own Sphinx plugin (scope) to manage all my case. To succeed I used the meta directive that can be place on the top of the file.
Thus
a_doc_for_basic.rst
.. meta::
:scope: basic
Title
=====
My content
a_doc_for_code.rst
.. meta::
:scope: code
Title
=====
My content
And you can continue to use .. only:: directive on file
a_doc_for_all.rst
Title
=====
My content
.. only:: code
a piece of code
You can find plugin source here
As you can see the plugin is pretty simple and works thanks to regexp. That means (regexp) that there is limitation:
The directive .. meta:: :scope: must be place at the top of the file (no line before)
The directive .. meta:: :scope: must match the regexp ^\.\. meta::\s+:scope: ([a-zA-Z0-9_-]+)
The directive .. meta:: :scope: can manage multiple tag but you can easily update the plugin for your needs
Plugin deviate the original use of meta directive docutils.sourceforge.net/docs/ref/rst/directives.html#meta
After that you can build your doc using the following command
sphinx-build ... -t <tag> ...
sphinx-build ... -t code ...
Other thing, you can use the same toctree for all tag because when compiling a doc per tag the toctree will be edited by the plugin to generate a tree without reference to the no-matching documentation.
PS: my plugin is not perfect but I replied to my needs, you can inspired and update it.
When building html documentation, how do you force sphinx to report, or create an error, on links that don't exist?
Specifically, I have properties and methods within my Python project that have been removed or renamed, and it is hard to find all the dead links with the sphinx generated html output.
I feel like I'm staring at the answer here:
http://sphinx-doc.org/glossary.html, as descriped in the opening paragraph.
I'm obviously not understanding something.
Set the nitpicky configuration variable to True (you can also use the -n option when running sphinx-build).
In nitpicky mode, a cross-reference to a function (such as :func:`myfunc`), class, or other object that cannot be found will generate a warning message.
I think CheckExternalLinksBuilder is what you're looking for.
It's basically used by calling 'sphinx-build' with -b linkcheck option. Please see sphinx-build for more info. Also, take a look at the list of sphinx-extensions here and here.