I have a problem with C++ domain. In my index.rst I have
:cpp:func:`Hello()`
In hallo.rst I have the following lines:
.. cpp:function:: Hello
.. doxygenfunction:: Hello
The line with doxygenfunction works and I get the documentation generated for my function.
But the line with cpp:function doesn't work. Instead, I'm trying to generate a link for the Hello() function in the documentation.
I generated my C++ documentation with Sphinx, Doxygen and Breathe.
I don't know if I got your Question right. In the documentation of Breathe it is listed how to link a function.
doxygenfunction
This directive generates the appropriate output for a single function. The function name is required to be unique in the project.
.. doxygenfunction:: <function name>
:project: ...
:path: ...
:outline:
:no-link:
Check out: https://breathe.readthedocs.io/en/latest/directives.html#doxygenfunction
There is also an example page on how to link a single function: https://breathe.readthedocs.io/en/latest/function.html#function-example
Related
I am trying to run a script to modify the documentation built by sphinx hosted by Read the Docs (because some links are not properly handled). The script works when I try to build it locally, but either fails on the Read the Docs build or the changes do not get propagated to the web site.
The script I'm trying to run is super simple, it replaces some html links that are not properly converted by sphinx-markdown-tables:
#!/bin/bash
# fix_table_links.sh
FILE="_build/html/api_reference.html"
if [[ "$1" != "" ]]; then
FILE="$1"
fi
sed -E 's/a href="(.*)\.md"/a href="\1\.html"/g' -i ${FILE}
My readthedocs.yml looks like this:
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# Optionally build your docs in additional formats such as PDF and ePub
formats: all
# Optionally set the version of Python and requirements required to build your docs
python:
install:
- requirements: docs/requirements.readthedocs.txt
build:
os: ubuntu-20.04
tools:
python: "3.8"
jobs:
post_build:
- echo "Running post-build commands."
- bash docs/fix_table_links.sh _readthedocs/html/api_reference.html
There are two cases:
Case 1) Using the readthedocs.yml as above, the build fails because _readthedocs/html/api_reference.html does not exist, despite this directory being the place the documentation claims will get uploaded from here. An example failure of this run is here.
Case 2) If I change the final of readthedocs.yml to bash docs/fix_table_links.sh docs/_build/html/api_reference.html, then the build passes (example here). But the links are not updated on the Read the Docs site: they still point to markdown pages rather than their corresponding HTML pages, so it must not be the version that gets uploaded to the Read the Docs web site.
Wading through documentation, I can't figure out how do this. Has anybody done this before or have a better grasp on how Read the Docs builds work? Thanks!
If you're willing to rewrite the script as a Python function, then you can do this super easily by connecting it as an event handler for the build-finished event.
I've done something similar in one of my own repos, except I post-process a .rst file. It's not actually used on RTD, but I can see it works in the build logs. So it should work to post-process your HTML files as well, since the build-finished event would occur after they've been generated.
First, define the script as a function in your conf.py. It needs to have app and exception as parameters.
def replace_html_links(app, exception):
with open(FILE, 'r') as f:
html = f.read()
# stuff to edit and save the html
Then either define or add to your setup function:
def setup(app):
app.connect('build-finished', replace_html_links)
And that's it!
I'm using mkdocs to create html web pages and snippets extension to fragment my master documents into small pieces. I have an incomprehensible bug:
In the file file1.md I made:
--8<--
includes/some_rep/fragment1.md
includes/some_rep/fragment2.md
...
--8<--
And all is ok... but in another file2.md i made:
--8<--
includes/other_rep/oher_fragment1.md
--8<--
And got a non interpreted output :(
Does some one experimented similar bug?
Add pymdownx.snippets in the markdown_extensions
In a reStructuredText on Sphinx 2.x, I want to put a content that changes depending on the output format.
In any source document, say, index.rst, add the following lines:
.. role:: pdf(raw)
:format: pdf
.. role:: latex(raw)
:format: latex
.. role:: html(raw)
:format: html
.. |foo| replace::
:pdf:`PDF!`
:latex:`LaTeX!`
:html:`HTML!`
I am |foo|
I expect it shows "I am HTML!" when the output format is in HTML, "I am LaTeX!" if it's LaTeX (even after converting the product to PDF via pdflatex) and "I am PDF!" if it's PDF.
I make the HTML version using make html and I see only "I am HTML!" in a web browser as I expect:
Install rst2pdf. Put the following lines in conf.py:
extensions = [
'rst2pdf.pdfbuilder'
]
pdf_documents = [(
'index',
u'testRst2Pdf',
u'Test Title',
u'Sarah Author')]
Make the PDF version with
sphinx-build -b pdf ./source/ ./build/
Update. Below is the output. No error. I ran this using WSL 1 (Ubuntu 18.04).
Running Sphinx v2.4.3
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [pdf]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing testRst2Pdf...
index
resolving references...
done
writing testRst2Pdf...
done
build succeeded.
I see "I am PDF! LaTeX! HTML!" that includes all the three items.
Is there any way to get either "I am PDF!" or "I am LaTeX!" in the PDF file?
Note.
Before reporting this behavior as a bug, someone help me check if it's unexpected behavior or as-designed.
This question is derived from the other I asked earlier: StackOverflow: "Sphinx: Use a different directive for a different output format".
rst2pdf does not really have conditionals, but you might find the --strip-elements-with-class switch useful? Put the optional pieces into a class name and then if that class doesn't make sense for this format, remove it with the switch.
Manual is here https://rst2pdf.org/static/manual.html#command-line-options and I also blogged (basically a longer version of this first paragraph) about this https://rst2pdf.org/static/manual.html#command-line-options if more information would be useful.
How do you pass options to stack haddock from stack.yaml? I cannot find any clue to correct syntax neither in documentation nor in stack source code.
Documentation describes the following:
build:
haddock-arguments: ""
Naive haddock-arguments: "--odir=./docs" fails with type error:
…failed to parse field 'haddock-arguments': expected HaddockOptsMonoid, encountered String
I figured out that it expects it to be like:
build:
haddock-arguments:
odir: "./docs"
However it fails with error Unrecognized field in HaddockOptsMonoid: odir.
What is correct syntax of passing arguments from haddock manual to stack via stack.yaml? In my specific case, I want specify custom output directory.
After looking at the source I figured out that the syntax is
build:
haddock-arguments:
haddock-args:
- "--odir=./docs"
In a sample project this has the following result (notice the location of the docs directory deep down in .stack-work):
$ ls .stack-work/install/x86_64-linux/lts-6.3/7.10.3/doc/docs/ | cat
doc-index.html
frames.html
haddock-util.js
hslogo-16.png
index-frames.html
index.html
minus.gif
ocean.css
plus.gif
synopsis.png
The links in index.html are broken, so I'm slightly pessimistic that you can achieve what you want by passing arguments to haddock in this way.
How to include external file as Sphinx documentation similar to a code block?
And how can I make it style the syntax color?
Found it here: http://sphinx-doc.org/markup/code.html
.. literalinclude :: <path/to/file>
:language: <file_language>