I am building documentation with Sphinx-RTD.
I want to have a link somewhere, and be styled as a verbatim or preformatted text.
For example, say I have this verbatim:
ALTER TABLE
Is there a way to link it somewhere, say a :ref:... or even just a standard hyperlink?
If I am not mistaken the "Replacement Text" directive can help.
As reStructuredText doesn't support nested inline markup, the only way to create a reference with styled text is to use substitutions with the "replace" directive:
I recommend you try |Python|_.
.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/
So maybe something like this:
Click |altertable|_ to read details about |altertable|.
----
Blah blah blah
----
.. _altertable:
Here are the details about |altertable|: blah blah blah.
.. |altertable| replace:: ``ALTER TABLE``
Related
How to create a custom Id for headlines in Sphinx (Jinja)?
Sphinx defines Id same with the headline text by default, but I want to define a different Id
If you write this in text file :
Headline text
=============
After converting it to HTML file by Sphinx, it looks like this:
<span id="headline-text"></span><h2>Headline text<a class="headerlink" href="#headline-text" title="Permalink to this headline">¶</a></h2>
But I don't want this Id and I want to define my own custom Id for this tag
If text isn't English, the default value is 's-id{number}', which number sets by Sphinx.
Now I want to write something in another language and I'm looking for a way to change it.
After many searches, I came up with a way like the following, but the problem is that when I look at the HTML source, I see that it still has its own ID next to mine like following:
.. _my-custom-id:
مثال سرتیتر
============
And after converting to HTML:
<span id="s-id1"></span><span id="my-custom-id"></span><span id="id1"></span><h1>مثال سرتیتر<a class="headerlink" href="#my-custom-id" title="Permalink to this headline">¶</a></h1>
As you can see, this method still doesn't work and Sphinx still defines its default ID.
What is the solution?
How do I render a strikethrough (or line-through) in an adoc file?
Let's presume I want to write "That technology is -c-r-a-p- not perfect."
That technology is [line-through]#crap# not perfect.
As per Ascii Doc manual, [line-through] is deprecated. You can test here.
Comment from Dan Allen
It's important to understand that line-through is just a CSS role. Therefore, it needs support from the stylesheet in order to appear as though it is working.
If I run the following through Asciidoctor (or Asciidoctor.js):
[.line-through]#strike#
I get:
<span class="line-through">strike</span>
The default stylesheet has a rule for this:
.line-through{text-decoration:line-through}
You would need to do the same.
It is possible to customize the HTML that is generated using custom templates (Asciidoctor.js supports Jade templates). In that case, you'd override the template for inline_quoted, check for the line-through role and produce either an <s> or, preferably, a <del> instead of the span.
If you're only targeting the HTML backend, you can insert HTML code verbatim via a passthrough context. This can be done inline by wrapping the parts in +++:
That technology is +++<del>+++crap+++</del>+++ not perfect.
This won't help you for PDF, DocBook XML, or other output formats, though.
If the output is intended for HTML you can pass HTML.
The <s> HTML element renders text with a strikethrough, or a line
through it. Use the element to represent things that are no longer
relevant or no longer accurate.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s
To render as:
Example text.
use:
1. Pass inline:
Example +++<s>text</s>+++.
2. Pass-through macro:
Example pass:[<s>text</s>].
3. Pass block:
++++
Example <s>text</s>.
++++
I am using sphinxcontrib-httpdomain extension to write Sphinx documentation. This extension is able to generate a 'routing table' page which I defined like this.
I also defined a substitution which I use in my docs:
# conf.py
rst_epilog = """
.. |mongodb_icon| raw:: html
<span class="icon-dbs-mongodb"></span>
"""
However, when I put this substitution in the synopsis directive of HTTPDomain extension, it is rendered out as plain text...
.. http:post:: /companies/
:synopsis: Some text whatever |mongodb_icon|
How can I force this page (routing table) to render out my substitutions properly?
I looked through the Pandoc HTML template and I wasn't able to find an option to include a header to the reference section when using pandoc-citeproc. Currently the output looks like the following:
<div class="references">
<p>Some References</p>
</div>
How would it be possible to insert a <h3>Reference</h3> block directly above it? Neither the template nor the documentation mention a $reference$ variable. This is the relevant section of the HTML template:
$body$
$for(include-after)$
$include-after$
$endfor$
I would want to add something like this:
$body$
<h3>References</h3>
$references$
$for(include-after)$
$include-after$
$endfor$
As it says here, the way to do this is to end your document with a level-1 header with the name of the references section. If you use --number-sections and don't want the references section numbered, you can include {.unnumbered} or just {-} after the title.
There is a previous question that explains how to add a color span to some reStructuredText.
To recap the procedure:
First, you have the role.
.. role:: red
An example of using :red:`interpreted text`
It translates into as follows.
<p>An example of using <span class="red">interpreted text</span></p>
Now, you have the red class, you can use CSS for changing colors.
.red {
color:red;
}
How do you do this if you want text that spans multiple lines? For example:
.. role:: red
:red:`paragraph 1
paragraph 2
paragraph 3`
Where paragraph 1, 2, & 3 would all be "red". If I try to do this I get the warning message:
WARNING: Inline interpreted text or phrase reference start-string without end-string.
It doesn't create the span and inserts ":red:" into the text. It just doesn't interpret this as a string (as the warning suggests).
Basically, can this be done in reStructuredText, and if it can, how?
I'm using Sphinx 1.1.3.
There are a number of ways to do this, but one of them is to use the class directive:
.. class:: red
This is a paragraph.
This is another paragraph.
Most docutils HTML writers will put that into html output as a class html attribute, which you can then style with CSS.
In Sphinx, in particular, however, you may need to use rst-class instead of class in at least some cases. See: https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/basics.html
Also, many block-level elements in RestructuredText take a :class: parameter which does pretty much the same thing.