I know reStructuredText has this directive:
.. code:: bash
gedit pohl.m
which renders a code block. Is there some way to get syntax highlighting for inline snippets like this:
Do edit the file, type ``gedit pohl.m`` into a terminal.
The backticks mark it as code, but I'd like to highlight it with pygments like the block. Is this possible?
Having looked into this some more I stumbled upon the document reStructuredText Interpreted Text Roles. From this document:
Interpreted text uses backquotes (`) around the text. An explicit role marker may optionally appear before or after the text, delimited with colons. For example:
This is `interpreted text` using the default role.
This is :title:`interpreted text` using an explicit role.
It seems that there is a code role, so you can simply type
:code:`a = b + c`
to render an inline code block. To get syntax highlighting you can define a custom role. For example
.. role:: bash(code)
:language: bash
which you can then use like so:
Here is some awesome bash code :bash:`a = b + c`.
Note that the role definition must be placed before references to the role.
Note, the document I link to makes no mention of the version of docutils to which it refers. The code role is not available in docutils 0.8.1 (which is the only version I have to test against).
For me I had to create a docutils.conf file in the Sphinx's configuration directory (where conf.py resides).
It had the following contents:
[restructuredtext parser]
syntax_highlight = short
See this answer for more information on the above
To set the role globally, in the conf.py file, I created a rst_prolog variable. The string inside it will be included at the beginning of every source file that is read.
rst_prolog = """
.. role:: python(code)
:language: python
:class: highlight
"""
In this highlight class was necessary for proper Python highlighting.
See this answer for more information on the above
Related
I want to include full example scripts in Sphinx documentation. I originally simply duplicated an example file using a .. code:: directive, dropping in the entire python and json files for the example.
I then found the .. include:: directive, which lets to link to files by providing their relative path, and by using the code option, "The argument and the included content are passed to the code directive". This works fine for my python files, because the default decoding and highlighting for the code directive is python. But my json files are not highlighted as json. How do I indicate what code format the code directive should use to parse the code?
This is what I am using.
.. include:: ../../examples/my_example.json
:code:
I tried adding changing the second line to :code: json with no effect.
This is what I had originally, but want to replace so the example code does not have to be maintained in both the documentation and the examples.
.. code-block:: json
:name: my_example.json
:caption: my_example.json
{
"field1": "attribute1",
"field2": "attribute2",
"field3": true,
...
}
The solution is to instead use the literalinclude directive which has a language option. This is how it should look.
.. literalinclude:: ../../examples/my_example.json
:language: json
Note that literal include also supports options like linenos, lines, start-after, and end-before, caption, and name.
I need to include the following code in a .tex file that is generated from a custom template via RMarkdown, in order to get rid of an error. However, if I try it as below in the YAML heading:
header-includes:
\newenvironment{CSLReferences}%
{}%
{\par}
it gets parsed into the .tex file as single line, like \newenvironment{CSLReferences}% {}% {\par}, thus commenting out everything after %. So how can I change the YAML part so that it correctly gets interpreted as 3 different lines?
Instead of worrying about the markdown parsing, you can write the command in a single line:
header-includes:
\newenvironment{CSLReferences}{}{\par}
Alternatively avoid all these annoying problems with markdown parsing and put your definition in a .tex file which you can include via
includes:
in_header: header.tex
After some trials & searching this works (found a solution while writing the question):
header-includes:
- "\\newenvironment{CSLReferences}%"
- "{}%"
- "{\\par}"
Interestingly, I couldn't find much in the official documentation.
EDIT:
As #samcarter mentioned in the comments & an answer, in this particular case a single line would've been enough, as
header-includes:
\newenvironment{CSLReferences}{}{\par}
I've found the following .travis.yml template.
I've noticed this:
repo: {GITHUB_USER}/{PROJECT_NAME}
Is this a special .yml variable syntax I'm not familiar with? Where can I set these values (GITHUB_USER, PROJECT_NAME)?
I know I can use environment variables, like so:
repo: $GITHUB_USER/$PROJECT_NAME
but this syntax looks different.
That is not a valid YAML file. After the first } the YAML parser will expect a block style continuation. This means either a key that aligns with repo or outdenting. Instead it finds a / and any YAML parser should throw an error on that.
This looks like a template for a YAML file, e.g. using something like the following in Python after loading the contents of the file in string templ:
templ.format(**dict(GITHUB_USER="Janez", PROJECT_NAME="test"))
On the other hand the recommended extension for YAML files has been .yaml for many more years than Travis exists, so maybe that is why they used the .yml extension.
Background
Pandoc's markdown lets you specify extensions for how you would like your markdown to be handled:
Markdown syntax extensions can be individually enabled or disabled by appending +EXTENSION or -EXTENSION to the format name. So, for example, markdown_strict+footnotes+definition_lists is strict markdown with footnotes and definition lists enabled, and markdown-pipe_tables+hard_line_breaks is pandoc’s markdown without pipe tables and with hard line breaks.
My specific question
For a given pandoc conversion where, say, I use grid tables in my source:
pandoc myReport.md --from markdown+pipe_tables --to latex -o myReport.pdf
How can I write a pandoc YAML block to accomplish the same thing (specifying that my source contains grid tables?)
A generalized form of my question
How can I turn extensions on and off using pandoc YAML?
Stack Overflow Questions that I don't think completely answer my question
Can I set command line arguments using the YAML metadata - This one deals with how to specify output options, but I'm trying to tell pandoc about the structure of my input
What can I control with YAML header options in pandoc? - Answerers mention pandoc's templates, but neither the latex output template nor the markdown template indicate any sort of option for grid_tables. So, it's not clear to me from these answers how knowing about the templates will help me figure out how to structure my YAML.
There may also not be a way to do this
It's always possible that pandoc isn't designed to let you specify those extensions in the YAML. Although, I'm hoping it is.
You can use Markdown Variants to do this in an Rmarkdown document. Essentially, you enter your extensions into a variant option in the YAML header block at the start of the your .Rmd file.
For example, to use grid tables, you have something like this in your YAML header block:
---
title: "Habits"
author: John Doe
date: March 22, 2005
output: md_document
variant: markdown+grid_tables
---
Then you can compile to a PDF directly in pandoc by typing in your command line something like:
pandoc yourfile.md -o yourfile.pdf
For more information on markdown variants in RStudio: http://rmarkdown.rstudio.com/markdown_document_format.html#markdown_variants
For more information on Pandoc extensions in markdown/Rmarkdown in RStudio:
http://rmarkdown.rstudio.com/authoring_pandoc_markdown.html#pandoc_markdown
You can specify pandoc markdown extension in the yaml header using md_extension argument included in each output format.
---
title: "Your title"
output:
pdf_document:
md_extensions: +grid_tables
---
This will activate the extension. See Rmarkdown Definitive Guide for details.
Outside Rmarkdown scope, you can use Pandocomatic to it, or Paru for Ruby.
---
title: My first pandocomatic-converted document
pandocomatic_:
pandoc:
from: markdown+footnotes
to: html
...
As Merchako noted, the accepted answer is specific to rmarkdown. In, for instance, Atom md_extensions: does not work.
A more general approach would be to put the extensions in the command line options. This example works fine:
----
title: "Word document with emojis"
author: me
date: June 9, 2021
output:
word_document:
pandoc_args: ["--standalone", "--from=markdown+emoji"]
----
For people stumbling across this in or after 2021, this can be done without Rmarkdown. You can specify a YAML "defaults" file, which basically includes anything you could want to configure.
In order to do what OP wanted, all you'd need to do is
from: markdown+pipe_tables
in the defaults file, then pass it when you compile.
You can also specify the input and output files, so you can end up with the very minimal command
pandoc --defaults=defaults.yaml
and have it handle the rest for you. See https://pandoc.org/MANUAL.html#extensions for more.
I'm using Sphinx on Windows.
Most of my documentation is for regular users, but there are some sub-pages with content for administrators only.
So I want to build two versions of my documentation: a complete version, and a second version with the "admin" pages excluded.
I used the exclude_patterns in the build configuration for that.
So far, it works. Every file in every subfolder whose name contains "admin" is ignored when I put this into the conf.py file:
exclude_patterns = ['**/*admin*']
The problem is that I'd like to run the build once to get both versions.
What I'm trying to do right now is running make.bat twice and supply different parameters on each run.
According to the documentation, I can achieve this by setting the BUILDDIR and SPHINXOPTS variables.
So now I have a build.bat that looks like this:
path=%path%;c:\python27\scripts
rem BUILD ADMIN DOCS
set SPHINXOPTS=
set BUILDDIR=c:\build\admin
call make clean
call make html
rem BUILD USER DOCS
set SPHINXOPTS=-D exclude_patterns=['**/*admin*']
set BUILDDIR=c:\build\user
call make clean
call make html
pause
The build in the two different directories works when I delete the line set BUILDDIR=build from the sphinx-generated make.bat file.
However, the exclude pattern does not work.
The batch file listed above outputs this for the second build (the one with the exclude pattern):
Making output directory...
Running Sphinx v1.1.3
loading translations [de]... done
loading pickled environment... not yet created
Exception occurred:
File "C:\Python27\lib\site-packages\sphinx-1.1.3-py2.7.egg\sphinx\environment.
py", line 495, in find_files
['**/' + d for d in config.exclude_dirnames] +
TypeError: coercing to Unicode: need string or buffer, list found
The full traceback has been saved in c:\users\myusername\appdata\local\temp\sphinx-err-kmihxk.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>.
What am I doing wrong?
Is the syntax for exclude_patterns in the sphinx-build command line different than in the conf.py file?
Or is there a better way to build two different versions in one step?
My first thought was that this was a quoting issue, quoting being notoriously difficult to get right on the Windows command line. However, I wasn't able to come up with any combination of quoting that changed the behavior at all. (The problem is easy to replicate)
Of course it could still just be some quoting issue I'm not smart enough to figure out, but I suspect this is a Sphinx bug of some kind, and hope you will report it to the Sphinx developers.
In the meantime, here's an alternate solution:
quoting from here:
There is a special object named tags available in the config file. It can be used to query and change the tags (see Including content based on tags). Use tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to change
This allows you to essentially pass flags into the conf.py file from the command line, and since the conf.py file is just Python, you can use if statements to set the value of exclude_patterns conditionally based on the tags you pass in.
For example, you could pass Sphinx options like:
set SPHINXOPTS=-t foradmins
to pass the "foradmins" tag, and then check for it in your conf.py like so:
exclude_patterns = blah
if tags.has('foradmins'):
exclude_patterns = []
That should allow you to do what you want. Good Luck!