I want a doxygen comment in my C++ code to refer to a certain function; say, in a different namespace: foo::bar(). And let's ignore the possibility that this function is overloaded. And I would also like the function's name to be set the same way as content within backticks in my doxygen comments.
With that in mind, which of the following are supposed to produce the effect I've described?
#ref foo::bar
#ref foo::bar()
#ref `foo::bar`
#ref `foo::bar()`
or - perhaps something else?
The documentation of the \ref command states:
\ref ["(text)"]
Creates a reference to a named section, subsection, page or anchor. For HTML documentation the reference command will generate a link to the section. For a section or subsection the title of the section will be used as the text of the link. For an anchor the optional text between quotes will be used or if no text is specified. For LATEX documentation the reference command will generate a section number for sections or the text followed by a page number if refers to an anchor.
With the \ref command the first argument is the <name> and a <name> cannot contain a backtick.
To obtain the requested possibility of a mono spaced link one can for HTML (only!) adjust / extend the used entry in the style sheet.
As a starter:
In the default doxygen stylesheet doxygen.css we have:
a.el {
font-weight: bold;
}
By changing this entry to e.g.
a.el {
font-family: monospace, fixed;
font-weight: normal;
}
Best is not to redefine the doxygen.css and give this as setting HTML_STYLESHEET,
but create a new, extra, stylesheet and specify this in HTML_EXTRA_STYLESHEET.
Note that this will influence all links not only the \ref ones.
Related
I have a .. toctree as part of a sphinx page, which includes relative links to other rst files in my package. How can I include a link to a subsection of a given page, rather than the full page itself?
I took a stab at
.. toctree::
page#section
But that didn't work. Any help is great.
After much hackery, I've come to the following solution, but I should first state that my goal was to:
have the heading NOT appear in the content body
have the heading appear in the TOC
So basically linking from the TOC to an arbitrary but invisible part of a document.
I needed this in order to be able to link to methods in some source code documentation rendered with Sphinxcontrib PHPDomain - these methods generate section links of their own, but do not get added into the TOC by default.
Step 1:
At the top of your RST file which needs this linking functionality, add a new role as such:
.. role:: hidden
:class: hidden
Step 2:
Somewhere in the content, use this role as such:
:hidden:`My Arbitrary Location`
"""""""""""""""""""""""""""""""
Step 3:
Add new CSS to the project (usually done by adding a CSS file into _static, or defining a style sheet or something like that - see this):
.rst-content .hidden {
display: none;
}
nav .hidden {
display: unset;
}
This forces the heading to be hidden in the content, but shown in the TOC.
Then, reuse the role as necessary in other documents.
Note that if your goal is to link to arbitrary locations in the document and still have the headings show up in the content, just change the CSS to style the headings to your liking rather than hide them.
When creating the ToC, Sphinx is including all headings and subheadings of referenced files within the configured tree depth. So you can simply not start the page with a heading and insert the heading at the point you want the ToC to point to, e.g.:
.. _my-rst-file:
**You can use bold print here if you want. This will not appear in the ToC**
.. rubric:: Or the "rubric" directive
And here some more text, normal font weight.
Here comes the heading that will appear in the ToC
""""""""""""""""""""""""""""""""""""""""""""""""""
And so on...
You need to include the page reference in the ToC as usual.
So in the ToC, you have:
.. toctree::
my_rst_file
In our example, the build result (HTML, PDF, whatever) will only have a reference to Here comes the heading that will appear in the ToCin the ToC.
I'm writing some text that will be converted to HTML, as a long single page.
Can't figure out how to make links to sections as in HTML using #some-id, so that a user when clicking it will go up or down the web page to
<h2 id="some-id">Section A</h2>
<p>Lot's of lines</p>
Go to section
What you're referring to is called an "internal cross reference".
The markup for an internal cross reference is:
<<id,caption>>
where id is an element on the page that has an identifier, typically a title, and caption is optional text that should appear in the link.
You can link to titles that have auto-generated ids, but the formation of the ids could vary based on the attributes idprefix and (for Asciidoctor) idseparator. The default is to make the title text lowercase, prefix with an underscore, and replace spaces and other punctuation with underscores. The id for the title "Let's make a game!" would be _lets_make_a_game.
It is often better for you to specify your own id that will remain stable even if you edit the text of a title. You can do so with:
[[id,label]]
where id is the identifier you want to specify, and label is the optional, default label that may be used for the cross reference (if the cross reference itself doesn't specify a caption).
If the element that your cross reference points to is a title, you can omit the caption and the label, and the link will use the title's text as its own text.
For Asciidoc, see: http://asciidoc.org/userguide.html#_internal_cross_references
For Asciidoctor, see: https://asciidoctor.org/docs/user-manual/#internal-cross-references
Usage Example:
This is how we assign an ID:
== Debug Running Pods [[debug_running_pods]]
Refer to an ID:
<<debug_running_pods>>
Another option is to use the link: macro. Here's an example from one of my Asciidoctor docs:
link:#_explore_the_public_directory[17.4. Explore the `public` directory]
Info about this is in https://asciidoctor.org/docs/user-manual/#url. Here's an excerpt from the relevant part:
When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the link macro.
I couldn't find a directive that handles this.
Suppose to have a single rst document and for some reason you want to hide a single section during the build (no matter if HTML, PDF..), like:
Visible section
===============
Here some example I want to show
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
is there a .. hidden:: directive that handle this, I'm thinking of something like:
Visible section
================
Here some example I want to show
.. hidden::
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
.. visible::
Another section
===============
Other visible section in both text and final document
You can use comment syntax: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#comments
The version of Sphinx I have got automatically generates an index.rst file that starts with a comment like this:
.. sphinx-quickstart on Sat Jun 22 15:48:19 2019.
You can adapt this file completely to your liking, etc
It does not show up in the documentation. You can start lines with two dots and a space followed by your own text and that does not show up either. You need to make sure that all the lines you create are indented the same as the first line. Then the whole section does not show up. Also make sure there is an empty line before the section and after it (unless it is the first section in the file or the last one)
Here is a solution to hide a section, so it doesn't show up in the HTML ouput.
However, this does not affect the build.
The idea is to use the class diretive and that way be able to assign a CSS class to the section(s). In CSS you can then define the class with display: none (or any other CSS).
For you example it would look like (note the identation):
Visible section
================
Here some example I want to show
.. class:: hidden
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
Another section
===============
Other visible section in both text and final document
In your css you add the following styling:
.hidden { display: none }
Here is a link that explains how to add custom CSS to Sphinx.
I have a problem with using Sphinx-doc's :ref: role, I put a label above a paragraph and then I try to link to that label from another doc but inside the same project.
The label I use in one document:
.. _hal_1k_1p:
And the ref I try to use to link to that label:
:ref:`Link title hal_1k_1p`
But I only get this error message when building the doc:
WARNING: undefined label: link title hal_1k_1p (if the link has no
caption the label must precede a section header)
What am I doing wrong?
Okay, looking at :ref: you need to have this:
:ref:`Link title <ha1_1k_1p>`
to link to that label.
Ensure you have angle brackets surrounding your label like so: <label>
First make sure that your ref is in the format:
Label:
.. _yourlabel:
Reference:
This is a reference to :ref:`yourlabel`.
or (if you want to give it a custom name)
This is a reference to :ref:`my very own label <yourlabel>`.
The label definition contains the leading underscore (_) while the reference doesn't! Also make sure that you didn't accidentally copy the colons from the label definition (:) to the reference.
If that doesn't help try switching languages back to english temporarily in your conf.py:
language = 'en'
If you see that this works you can switch back. Somehow this solved my problem. Maybe related to: https://github.com/sphinx-doc/sphinx/issues/1300
I have a .. toctree as part of a sphinx page, which includes relative links to other rst files in my package. How can I include a link to a subsection of a given page, rather than the full page itself?
I took a stab at
.. toctree::
page#section
But that didn't work. Any help is great.
After much hackery, I've come to the following solution, but I should first state that my goal was to:
have the heading NOT appear in the content body
have the heading appear in the TOC
So basically linking from the TOC to an arbitrary but invisible part of a document.
I needed this in order to be able to link to methods in some source code documentation rendered with Sphinxcontrib PHPDomain - these methods generate section links of their own, but do not get added into the TOC by default.
Step 1:
At the top of your RST file which needs this linking functionality, add a new role as such:
.. role:: hidden
:class: hidden
Step 2:
Somewhere in the content, use this role as such:
:hidden:`My Arbitrary Location`
"""""""""""""""""""""""""""""""
Step 3:
Add new CSS to the project (usually done by adding a CSS file into _static, or defining a style sheet or something like that - see this):
.rst-content .hidden {
display: none;
}
nav .hidden {
display: unset;
}
This forces the heading to be hidden in the content, but shown in the TOC.
Then, reuse the role as necessary in other documents.
Note that if your goal is to link to arbitrary locations in the document and still have the headings show up in the content, just change the CSS to style the headings to your liking rather than hide them.
When creating the ToC, Sphinx is including all headings and subheadings of referenced files within the configured tree depth. So you can simply not start the page with a heading and insert the heading at the point you want the ToC to point to, e.g.:
.. _my-rst-file:
**You can use bold print here if you want. This will not appear in the ToC**
.. rubric:: Or the "rubric" directive
And here some more text, normal font weight.
Here comes the heading that will appear in the ToC
""""""""""""""""""""""""""""""""""""""""""""""""""
And so on...
You need to include the page reference in the ToC as usual.
So in the ToC, you have:
.. toctree::
my_rst_file
In our example, the build result (HTML, PDF, whatever) will only have a reference to Here comes the heading that will appear in the ToCin the ToC.