I'm trying to have a variable in conf.py that inserts a link that is applied on a string:
rst_epilog = """
.. |support| replace:: `support team <support#blabla.com>`_
"""
In this case 'support team' would turn into a link pointing to the email address.
Unfortunately, this does not work and the build breaks.
So I've tried dumping HTML in there, not knowing when the substitution happens, but it happens before HTML conversion, so that does not work in my output.
rst_epilog = """
.. |support| replace:: support team
"""
Any idea I could do this with a variable?
Use this substitution definition:
.. |support| replace:: support team support#blabla.com
support#blabla.com is automatically recognized as a mailto link.
The |support| substitution reference produces the following output:
support team <a class="reference external" href="mailto:support%40blabla.com">support<span>#</span>blabla<span>.</span>com</a>
An alternative is to use a raw-html role (see http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw).
Add this to conf.py:
rst_epilog = """
.. role:: raw-html(raw)
:format: html
.. |support| replace:: :raw-html:`support team`
"""
Related
It is possible to make work mermaid inside \.md file with MyST md driver ?
For now the only way I found is
$ tail conf.py
extensions = [ 'recommonmark', 'sphinxcontrib.mermaid']
from recommonmark.transform import AutoStructify
def setup(app):
app.add_transform(AutoStructify)
$
The below is rendered with recommonmark:
```mermaid::
graph LR
a --> b
```
but not with MyST-parser
I have open this issue in MyST: https://github.com/executablebooks/MyST-Parser/issues/366
Note: recommonmark does not render correctly tables that's why I try to use MyST-parser
mermaid is prefectly integrated to MyST-parser.
You only need to call it like that with {mermaid}:
```{mermaid}
graph LR
a --> b
```
No need to define in conf.py a def setup(app): only:
extensions = ['myst_parser', 'sphinxcontrib.mermaid']
I installed the sphinxcontrib-plantuml extension which works fine if I run the HTML builder e.g. with following testmodule.rst file for a corresponding testmodule.py file:
testmodule module
=================
.. automodule:: testmodule
:members:
:undoc-members:
:show-inheritance:
.. uml::
Alice -> Bob: Hi!
Alice <- Bob: How are you?
This adds the UML diagram at the very end of the document. Unfortunately I didn't find out how to embed a UML diagram anywhere in the documentation e.g. somewhere in the middle of a methods docstring block.
Does anyone know how to do that?
Adding the UML diagram directly in the docstring section didn't work for me.
But following worked for me:
Put plantuml code in separate file e.g. diagram.uml:
#startuml
Alice -> Bob: Hi!
Alice <- Bob: How are you?
#enduml
Add the plantuml directive with the filename at the desired place in the docstring. E.g.:
def example():
"""
some text
.. uml:: diagram.uml
some more text
"""
...
I have tried the extension sphinx-tabs. I use Python 3.8 and the latest Sphinx ver.
I install with pip and add to conf.py but my code is never displayed properly.
In conf.py I have this:
extensions = ['sphinx_tabs.tabs']
My code is simple:
.. tabs::
.. tab:: tab1
Content for tab one
.. tab:: tab2
Content for tab two
This just produces the text:
tab1
tab2
Both appear to be hyperlinks but do not actually link anywhere.
Two things that are different between your code and mine:
I found I needed extra lines everywhere, and
for code especially, the code-block tag is great! (otherwise just go with tab).
.. tabs::
.. code-tab:: cpp
auto hello = someCPlusPlusFunction();
.. code-tab:: python
howdy = some_python_function()
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.
Given a yaml file that contains html, like this:
template : |+
<div>Hello, world</div>
Is it possible in Vim (version 7.3.087) to highlight the html portion with html syntax highlighting?
I found the post Different syntax highlighting within regions of a file, which seems to have exactly the concept I was looking for, but I cannot get it to work as expected with yaml. I'd expect to be able to do the following (as suggested in the link):
" .vimrc
" include the code from the above link
call TextEnableCodeSnip('html' ,'#{{{html' ,'#html}}}', 'SpecialComment')
Then have the yaml as, for example:
template : |+ #{{{html
<div>Hello, world</div>
#html}}}
Unfortunately this does not work as expected i.e. the html code remains entirely highlighted with yaml. I've also noted that with my configuration (MacVim 55), this doesn't work in text files either.
I'd be grateful for your thoughts or suggestions, and thank you for reading.
check out my related question: Trouble using Vim's syn-include and syn-region to embed syntax highlighting. There I am trying to embed Python within TeX, but I think the solution might work for your case, too.
I think you want to do something like this:
let b:current_syntax = ''
unlet b:current_syntax
runtime! syntax/yaml.vim
let b:current_syntax = ''
unlet b:current_syntax
syntax include #YaML syntax/yaml.vim
let b:current_syntax = ''
unlet b:current_syntax
syntax include #HTML syntax/html.vim
syntax region htmlEmbedded matchgroup=Snip start='#{{{html' end='#html}}}' containedin=#YaML contains=#HTML
hi link Snip SpecialComment
let b:current_syntax = 'yaml.html'
The block with the runtime! command might be unnecessary if your YaML is already highlighted.
You could try to add the following in your .vimrc:
autocmd BufRead,BufNewFile *.yaml setfiletype html.yaml
A yaml file will be considered to be both of type yaml and html and both syntax color scheme should be applied but I don't really know how conflicts between the two schemes are dealt with...
It looks like you want to move the start pattern to the beginning of the next line:
template : |+
#{{{html
<div>Hello, world</div>
#html}}}
More details:
I'm on WinXP, but I saw almost the same behavior that you described.
When in a file with filetype yaml, after calling TextEnableCodeSnip I didn't see a change until I moved the start pattern down the the beginning of the next line. I was able to see the syntax highlighting work in a file with no filetype though, so this still a chance this won't work for you.
I used Maxy-B's solution. My code, in particular, is a bit different so I thought to post it for posterity:
~/.vim/after/syntax/yaml.vim
let b:current_syntax = ''
unlet b:current_syntax
syntax include #HTML syntax/html.vim
syntax region htmlCode start=#^html:#hs=e+1 end=+^\w+he=s-1,me=s-1
\ contains=#HTML
let b:current_syntax = ''
unlet b:current_syntax
syntax include #TEX syntax/tex.vim
syntax region texCode start=#^tex:#hs=e+1 end=+^\w+he=s-1,me=s-1
\ contains=#TEX
This highlights the top-level YAML nodes html and tex with those respective types of code. It's not very dynamic, but it suits my purpose and this may serve as helpful guideline for someone doing something similar. It'll highlight the following as expected (or at least, as I expect it), for example:
regular: # yaml
- yaml # yaml
html:
<b>hello</b> # html
tex:
\begin{document} # tex
\end{document} # tex
the-end: may be necessary # yaml