Questions tagged [docutils]
a general purpose document processing system written in Python.
185
questions
0
votes
0
answers
23
views
How to create new documents with a sphinx extension
From a sphinx extension, how do I create new documents (new page) under the current document that called my extension. I.e, I have an extension that is called from a rst file.
Something like:
foo.rst
...
0
votes
1
answer
39
views
How to add a reference in a Sphinx custom directive?
I'm creating a custom directive to display the list of all the available components in pydata-sphinx theme. I try to avoid using the raw directive so I'm building a custom one to remain compatible ...
1
vote
0
answers
51
views
How to loop over all documents and get meta information about existing directives in Sphinx?
I would like to create a custom Sphinx extension, that shows a list of all figures. Also see related question How to create list of all figures (tables) in Sphinx?
In the Sphinx documentation there is ...
0
votes
0
answers
43
views
Display a literalinclude block within a README.rst in GitHub
Goal. Display a literalinclude block within a README.rst in GitHub.
Problem. I'm working on generating documentation for a Python project using Sphinx. The README.rst file has a literalinclude block (...
0
votes
0
answers
78
views
Error using literalinclude with sphinx in .rst
I'm working on generating documentation for a Python project using Sphinx. I want to include code snippets from example files using the literalinclude directive. However, I keep getting the error &...
0
votes
0
answers
100
views
Sphinx adds span with class colon to the header
We have a project which produces html from rst files, using Sphinx. Earlier we used Sphinx version 2.1 and after upgrade to version 6.1.3 a sideeffect occurs where our headers defined like this:
:...
0
votes
0
answers
50
views
How can I implement automatic multilevel list numbering in sphinx restructedtext?
How can I implement automatic multilevel list numbering in sphinx reStructuredText?
Let's say there is a to-do list somewhere in the document:
(here the numbering is manual)
1. Do something #1
1....
0
votes
0
answers
38
views
How to make reStructuredText ASCII art that includes backslash (`\)`? [duplicate]
I would like to include some ASCII art in a doc-string. However, even inside literal blocks, Sphinx seems to interpret \ as the escape sequence. Is there a reStructuredText environment in which the ...
1
vote
3
answers
391
views
reStructuredText: Automatic table of contents for standalone .rst file
I'm a Markdown user but recently I came across reStructuredText and I wanted to take advantage of its features to create technical documents in pdf.
I know this markup language is mainly used with ...
0
votes
2
answers
223
views
How to programmatically create doctrees in Sphinx?
I'm creating a Sphinx extension that generates a pretty huge number of RST files.
Since I formally know the content of them, I'd like to gain time and space by directly writing the docutils, skipping ...
0
votes
1
answer
65
views
Create directive which wraps other directives inside
We are trying to create a directive which wraps other directives inside. The following example will show an example:
Directives
==========
.. service_card_wrapper::
.. service_card::
.. ...
0
votes
1
answer
245
views
Pages not showing on side menu
I am using Sphinx and ReStructuredText to create documentation, but even though all pages were created the same way, only 4 out of 8 are showing on the side menu. This is my table of contents:
.. ...
1
vote
0
answers
131
views
Nested references in custom directive
As part of a custom directive I am trying to support nested references. I have re-worked the todo example to demonstrate what I am looking for.
The complete repo is here:
https://github.com/martynp/...
2
votes
0
answers
116
views
How to create a new document in Sphinx/docutils by API?
I' writing a new extension for Sphinx as a domain offering multiple directives, roles and indices for the hardware description language VHDL. This extension shall be able to auto document language ...
0
votes
1
answer
45
views
Parse raw rst string using nested_parse
I'm writing a sphinx extension that transforms a custom directive into a flat-table.
From inside the .run(self) method, I build a complete flat-table declaration in pure .rst, and I'd like to feed ...
0
votes
1
answer
60
views
Why does the docutils/Sphinx "include" directive represent a potential security hole?
The source of the claim is in the Docutils documentation, at https://docutils.sourceforge.io/docs/ref/rst/directives.html#include:
Warning
The "include" directive represents a potential ...
0
votes
1
answer
121
views
Sphinx Using Domain Data/Indices
i was following the Tutorial for the “recipe” extension (https://www.sphinx-doc.org/en/master/development/tutorials/recipe.html).
I am a little confused as the compiled html side doesn't show the ...
0
votes
0
answers
34
views
Custom sphinx directive fails when the content contains a nested glossary 'term' role
I have developed a sphinx extension for creating dependencies between different sections of a document. The primary application is plain text requirements management.
The main object in the extension ...
1
vote
0
answers
42
views
Invoking other directives from my own bespoke directive
I'm making a extension for sphinx, which takes c code block, compiles it with arguments and stores the assembly/listing output to separate file. I take the c code block, the asm code block and the ...
0
votes
0
answers
32
views
Combining replace and include in reStructuredText / Sphinx [duplicate]
I have been searching for a solution to this, but have just got even more confused!
I have a use case in my documentation to replace many instances of a name for a piece of equipment. I had been using ...
2
votes
0
answers
168
views
Nested nodes in sphinx extension
I am trying to make a sphinx extension (for html output) that generates a code block and inserts text and spans into it.
However when I create a literal_block (code block) and add inlines (spans) to ...
0
votes
0
answers
77
views
Create document without source, based on parse sources
With a sphinx extension, can I create additional sphinx pages not related to a specific source file?
source files:
foo.xml
bar.xml
output files:
foo.html
bar.html
wanted.html
The wanted file would ...
1
vote
1
answer
53
views
Supress cross reference hyperlink using exclamation mark
Prefixing the link with an ! suppresses the creation of a reference (e.g. :ref:`!no link` will be simply rendered as no link):
If you prefix the content with !, no reference/hyperlink will be created....
1
vote
0
answers
271
views
Sphinx- Print in a rst file a custom string variable defined in conf.py
I am defining in conf.py a string variable X that I would like to print in a rst file. Here is what I did :
In conf.py:
X = "MY CUSTOM STRING"
In the rst file:
Using |X|
But the html shows:...
0
votes
0
answers
375
views
Error: couldn't find version that satisfied requirements docutils==0.16 and no matching distribution found for docutils
While I was installing requirements.txt using: pip install -r requirements.txt.
I got this error
WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after ...
2
votes
1
answer
400
views
MyST-Parser: Auto linking / linkifying references to bug tracker issues
I use sphinx w/ MyST-Parser for markdown, and
I want GitHub or GitLab-style auto linking (linkfying) for references.
Is there a way to have MyST render the reference:
#346
In docutils-speak, this is ...
1
vote
1
answer
5k
views
docutils ERROR: Could not install packages due to an OSError: [Errno 2] No such file or directory
when I run pip show I get
FileNotFoundError: [Errno 2] No such file or directory: '/[my_home] /.local/lib/python3.8/site-packages/docutils-0.16.dist-info/METADATA'
and when I try to install docutils
...
0
votes
0
answers
233
views
Sphinx can't generate link text as literal
With Markdown, I can simply:
[`a link with monospace font`](https://www.example.com)
a link with monospace font
Note how the above line is properly rendered by SO's MD renderer: the link text is in ...
0
votes
1
answer
215
views
How to create an custom sphinx extention that works in latex
I created a super small extention to add the role "icon" in my doc. The idea is to write down the following :
I'm a folder :icon:`fa fa-folder`
I adapted some code find online and came up ...
3
votes
1
answer
599
views
Getting "Extension error (sphinx.environment.collectors.toctree)" when adding section nodes in Sphinx extension
I am trying to write a new Sphinx extension. A minimum example of an extension that does something similar to what I want is
from docutils import nodes
from docutils.parsers.rst import Directive
...
1
vote
1
answer
209
views
how to make a custom sphinx role that is also an external link?
I'm trying to extend Sphinx to have a new inline role called newcontrib. What it should do is take its content and (1) add some extra text to it, (2) make the text bold in the rendered output, and (3) ...
0
votes
1
answer
193
views
Extracting blocks of text from RST documents,files by :ref:?
I have a rst file SWAP.rst and i need to extract some specific data and put in a dictionary.
the file looks like this:
:baseID: SWAP_DF
The current used for the force ...
.. requirement::...
1
vote
0
answers
33
views
Transform reST list item for rst2html output
I have a reStructuredText document with todo list items:
Vim
===
- ✓ (2021-11-05) RST Section text object
(drop it in favor of env text object)
Probably should be based on the output of ``:Toc`` ...
1
vote
1
answer
45
views
Link directives in Rst grammar
How can I link directive with :doi: or :arxiv: in Rst.
I'm making a document with Rst, but when I try to link with arxiv, it shows broken link.
What I tried is below but not working.
<:doi:`10.1145/...
3
votes
1
answer
407
views
How to parse Sphinx custom directive content to docutil nodes
I'm trying to create a custom directive called LicenceDirective which looks like it:
.. licence: Some Software 3.0
:url: https://SomeSoftware.com/downloads
:path: /licence_file
CONTENT
The ...
1
vote
0
answers
335
views
Using packages in sphinx latex yields "unknown environment "package"" error message
I would like to create a table using latex elements in my sphinx documentation. So far I have added the following lines to my conf.py:
latex_engine = 'xelatex'
latex_elements = {
'preamble': r'''
...
0
votes
1
answer
492
views
Creating a sphinx extension involving a directive that takes in arguments
I am relatively new to writing sphinx extensions and would like to create one that takes in a number of keywords that are provided alongside the directive name inside the rst document and replaces it ...
3
votes
0
answers
269
views
Creating a custom table generator as a sphinx extension
I would like to create a custom directive that functions similar to docutil's list-table element, where I provide a list of arguments afterwards and use them to render a html table with a custom ...
3
votes
0
answers
193
views
Accented characters in Sphinx headings [closed]
I want to include accented characters in a Sphinx heading such that I will see the following result:
Finalé
I have tried the following strategies:
Use the unicode character directly such as:
Finalé
==...
1
vote
1
answer
2k
views
Docutils dependecy of Sphinx theme on readthedocs
I used to keep a project docs on readthedocs.io server. Here is the link CoFEA Initiative
Since the 3rd of April, it looks a bit broken (e.g. the main logo is aligned to the left while it should be ...
2
votes
2
answers
447
views
How do I unparse restructured text back into an rst file?
My question is a follow up to How to parse restructuredtext in python? where @mbdevpl provided code for parsing the file into a tree and doing some processing on the tree.
I want to autoformat Python ...
0
votes
1
answer
107
views
Exact docutils equivalent for :ref:
The following ReStructuredText contains the :ref: role, which is a Sphinx-extension:
Read more in :ref:`section-target`.
.. _section-target:
Section Title
=============
Text body.
Where
:ref:`...
0
votes
0
answers
112
views
Python Sphinx Validate and update schema
I'm using Sphinx to maintain docs on a project, I am generating a jsonschema document from a tool where all properties of objects are listed.
Those objects properties are documented in rst files, I ...
1
vote
0
answers
460
views
How do I set a caption for my generated code block in sphinx
Currently I am using the following code to generate a code block and show some information in it.
I'd like to set a caption like with the following rst directive.
.. code-block:: python
:caption: ...
1
vote
0
answers
52
views
SphinxDirective access to config._raw_config data
I need to do something very simple:
Access the tag generated by the command line:
$ sphinx-build -t <tag_name>
Example:
$ sphinx-build -t Foo
Will create a dictionary entry in:
sphinx.util....
3
votes
2
answers
332
views
Generating labels for nodes of a custom directive
Using the Sphinx "TODO" Directive example I would like to reference the todo instances embedded within a .rst file. For example, if the .rst file content contains:
.. todo:: foo
.. todo:: ...
0
votes
0
answers
62
views
What arguments to pass to inliner.parse() inside a custom role
I am defining my custom role that allows :ref: markups to be inside of it. The role is to be used as follows:
myrole:`some_text |SUBS| more_text`
A function replaces |SUBS| by
:ref:`some_target`
so ...
2
votes
1
answer
531
views
How do I make my sphinx directive add assets to _static folder?
I'm building a custom sphinx extension and Directive to render interactive charts on sphinx and ReadTheDocs. The actual data for a chart resides in a .json file.
In a .rst document, including a chart ...
0
votes
1
answer
250
views
How to get inline code ending with spaces with docutils/sphinx?
The following rST directive doesn't support trailing spaces:
:code:`foo `
Example:
>>> from docutils import core
>>> whole = core.publish_parts(""":code:`x `&...
3
votes
1
answer
102
views
Docutils difference between text and rawsource in nodes.Text?
When creating new nodes such as nodes.title, one needs to provide two strings:
rawsource
text
Often I see this:
nodes.title('foobar', 'foobar', ids=[id])
Or sometime...
nodes.target('', '')
I don'...