In the RST syntax, you can specify a :target: attribute for setting a link. I would like to link the image to a "materials.rst" doc page, whose main section title is "Materials"
But neither of these work as target value:
:target: `materials`_
:target: :doc: materials
:target: materials
How can I achieve this?
Not fixed even after 6 years, although :ref: works now across files just fine. However, you can't use :ref: within image or figure directives.
try using this:
:target: materials.html
...and hope for the best! The :target: role seems to accept HTML links only.
Let's assume there is some file named doc.rst which I want to access via the thumbnail in another document:
.. _doc:
Some Title
==========
...and then, in another document, I use the following solutions:
.. image:: /media/thumbnail_of_my_doc.jpg
:ref:`doc` <- doesn't compute
:target: doc (or doc.rst, or doc_) <- doesn't work either
:target: doc.html <- works im my case
The last option works just because I assumed the name of the HTML to be generated. What if I was wrong? This is a pure hack.
I can't believe no one got bothered to fix this.
I use RTD theme on Sphinx 4.2.0. all is updated to the newest versions.
Related
I am in process documenting my python library. I would like to add custom icons. I see I can add font awesome icons. However, I must not be googling very well or...
Is it possible to add custom icons to Sphinx(-rtd-theme)? If so, is there an example? I cannot find one. Thank you.
The closest thing I found was the sphinx-design package then using the avatars class with the {div} directive (Myst). e.g.:
:::{div}
<img src="images/whale_trace.png" class="sd-avatar-md sd-border-1">
:::
note: i use .md instead of .rst. Thus, I use the Myst parser. In order to copy the image over and use the right path, the conf.py file needs to be modified :
myst_enable_extensions = ["colon_fence", "html_image"]
adding html_image will all resolution of the image. See Myst documentation:
> Blockquote
HTML parsing to the rescue!
By adding "html_image" to myst_enable_extensions (in the sphinx conf.py configuration file), MySt-Parser will attempt to convert any isolated img tags (i.e. not wrapped in any other HTML) to the internal representation used in sphinx.
_
Context
I am using Sphinx to create technical documentation (not code-related). The input are several reStructuredText and SVG files. The output is created using the singlehtml builder (which is converted to PDF using weasyprint in a later step).
Problem
I would like to include a table of contents (TOC) in the final document. The default location for the TOC (sidebar) is not an option. I have to disable/hide the sidebar to generate a useful PDF.
Solutions (I have considered / tried)
toctree directive: Seems to only work with the sidebar, no matter what I try.
HTML Theming: I'm using it for styling the HTML output, but I would not know how to address the TOC issue.
Sphinx extensions: I wrote my own, but it's not very flexible and I'm still sure that others have already solved this problem.
Use latexpdf builder: Tried that and it solves the TOC problem, but it creates a few other problems and styling the document is so much easier for me using CSS.
Other tool than Sphinx: Is this a typical case of an XY problem? I would like to use reStructuredText and SVGs to generate a PDF, but I would be open to use something else than Sphinx.
Use the contents directive.
Here's the directive in its simplest form:
.. contents::
Language-dependent boilerplate text will be used for the title. The English default title text is "Contents".
An explicit title may be specified:
.. contents:: Table of Contents
As #mzjn already suspected, .. contents:: only lists the contents of the current file, but if I use .. include:: instead of .. toctree:: to include other documents, it works nevertheless. So what I'm currently using is this:
.. sectnum::
.. contents:: Table of Contents
:depth: 2
.. include:: intro.rst
.. include:: processes.rst
We are considering using Sphinx where I work and it appears to do everything we need. However, I am having issues getting it to match the required corporate template, which requires there to be some front matter pages inserted between the title page and table of contents.
If text is text is placed above the master table of contents in the .rst file, then it is placed above the TOC in the HTML output, but it is moved to below the TOC in the pdf output. I've also tried adding a hidden toc, but that didn't work either. The content also gets placed after the non-hidden toc.
.. toctree::
:hidden:
frontmatter
.. toctree::
:maxdepth: 2
contents_of_document
I know this has to be possible since people have published books using this tool, but I can't figure out how to do it.
I've tried this with sphinx 1.4.0 and 1.4.1. Is this something I need to add a latex sty or cls file to make it work? I would prefer not to since we would like to use both the HTML and PDF outputs.
Thanks
It looks like I need to RTFM. It is in chapter 10 to of the sphinx manual:
’tableofcontents’ “tableofcontents” call, default ’\tableofcontents’. Override if you want to generate a different table of contents or put content between the title page and the TOC.
So it order to do this, you need to learn some LaTeX as you will have to manually (or programmatically) write the from matter separately from the reST documentation.
I am using Confluence 4.0.3, I am trying to create a PDF layout/stylesheet so that it would grab the main title from the page content and move it to the title page.
What I have tried so far:
use the way that confluence suggests - it did not work well at all because it came with extra toc (np, I can hide it) and extra page content because it requires me to export from the parent level for it to work
I define a macro which contains the page title and I can use css to make it land on the title page. This works however if I was to export multiple docs this could pose a issue
Style the h1:first-child, this works but again on multiple docs this would be an issue.
Question: Is there a good way to do this on multiple doc exports? If not, does the page title have its own class that I can target instead of the h1:first-child? I tried h1.pagetitle (in their documentation) but it does not work, thanks
I used a user defined macro to put the title in and use the PDF export css to position it on the title page. This works as long as you are only exporting 1 document at the exporting level. If you are exporting 2 or more docs from the same exporting level then you can only define 1 of the macros or else they will all be at the same position on the title page.
This seems like the easiest way I found to implement something like this.
I would try employing a minor work-around. You could use a .asp page, which is located off of confluence, to pull the the pdf title and display it how you like. Then you can use an html-include macro to display the .asp page, and the pdf title it shows, wherever you like on confluence.
I want to link to a documentation of a file in RDoc. but the only way I could do is with the following markup:
configuration.rb[link:files/configuration_rb.html]
I would like to do it in a better way, something like this:
<file>configuration.rb</file>
Is there any existing markup rule to do this?
EDIT: of course I've tried without any markup like this configuration.rb but it shows the filename without the link :(
To display a link in rdoc
{Link label}[url ]
Sample
{Killer question}[http://http://stackoverflow.com/questions/2230954/is-there-any-way-to-easily-link-a-file-in-rdoc]
will create a link of the this question
Auto hyperlinked: MyClass
my_class.rb def my_method; end;
#my_method http:, mailto:, ftp:, www. link: (to local filesystem relative to
--op) (urls to images are rendered as inline image tags) label[url] (uses
label as hyperlink text) {multi word
label}[url] (uses label as hyperlink
text)
Ruby:
ClassNames, source_files.rb and
either
method_name_having_an_underscore or
#methodnamewithhash are hyperlinked to their documentation.
It sounds like you're looking for that second one, but I've never used it before so I can't give you a fully useful example.
Try not to use markup at all.
Look at RDoc's own documentation, they have similar links in the "Roadmap" paragraph. They markup is here.
Magic!