When I create a bullet list in Sphinx by typing
Text before the listing
- Item 1
- Item 2
Text after the listing
it renders as follows:
This behaviour is independent of the HTML theme (tried it with 'classic' and 'sphinx_rtd_theme') and the markup language (be it ReStructuredText or Markdown with the MyST parser).
While it seems intentional that an extra line is added before the first item, I find it distracting.
Can I suppress the extra line with an option or an HTML/CSS modification?
Sphinx supports custom CSS styling. If your CSS file is _static/css/custom.css, then you need to add its location to the conf.py file so that Sphinx finds it:
## conf.py
# These folders are copied to the documentation's HTML output
html_static_path = ['_static']
# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
'css/custom.css',
]
To implement the desired formatting, put the following into the above-mentioned custom.css file:
p { margin: 0; }
ul { margin-top: 0; }
as described here.
Related
I work on page drafts in my sphinx doc that I don't want to be available when I run sphinx-build.
for example I have files named _bob.md , _mistbuddy.md etc.
in my conf.py file I put:
exclude_patterns = [ '**/_*']
to ignore these file.
This works on load - files ignored :
However, if I then click on one of the topics, and ALL pages are available.
I have tried .. only:: <tag> however, a directive doesn't work on all contents in a file.
Thank you.
Background: I upgraded my repo to use python 3.9 (was 3.6). Upgraded all the packages to latest. Noticed my docs are not formatting with the sphinx-rtd-theme. See https://docs.members.loutilities.com/en/1.4.1.dev1/ as compared to https://docs.members.loutilities.com/en/1.4.0/
Reviewed the difference using chrome console, and with 1.4.0, the formatting is being done with https://docs.members.loutilities.com/en/1.4.0/_static/css/theme.css, but the theme.css file is missing in 1.4.1.dev1.
Note: reversion to old, previously working rtd-requirements.txt did not fix the issue.
repo code is in https://github.com/louking/members/tree/1.4.1.dev1/docs
specifically, conf.py has the following
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'membertility'
copyright = '2021, loutilities (Lou King)'
author = 'Lou King'
# The full version, including alpha/beta/rc tags
release = '1.0'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx_rtd_theme',
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.graphviz',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# see https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html
html_theme = 'sphinx_rtd_theme'
html_theme_path = ['_themes', ]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# set navigation depth
html_theme_options = {
'navigation_depth': -1,
'collapse_navigation': False,
'sticky_navigation': True,
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
html_context = {
'css_files': [
'_static/theme_overrides.css', # override wide tables in RTD theme
],
}
Don't use html_context for custom style, it will break your stylesheet.
html_static_path = ['_static']
html_css_files = ['theme_overrides.css']
Should work for you.
Is it possible to specify in the YAML metablock a pdf header and/or footer?Something you could set to appear on every page. This is in rmarkdown and will then be rendered to a pdf (using pandoc and knitr). I have not been able to find anything (header: and footer: sadly did not work!)
---
title: testpdf | test
footer: "test footer"
theme: "zenburn"
date: "`r Sys.Date()`"
output: "pdf_document"
fig_width: 12
fig_height: 6
fig_caption: true
---
There is no native pandoc-markdown support of headers and footers. However, since pandoc generates pdf documents through latex, you can tweak your latex template to accommodate those.
Create a new template from the default one :
pandoc -D latex > footer_template.latex
Add the following lines in the latex preamble (this is a very basic example that should produce a centered footer, see the fancyhdr user manual if you need something more advanced)
$if(footer)$
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyfoot[C]{$footer$}
$endif$
Finally, add this to your document yaml header :
output:
pdf_document:
template: test.latex
Your template should either be in ~/.pandoc/templates or in the same directory as test.rmd for this to work.
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
I'm getting the warning:
WARNING: document isn't included in any toctree
for files that exist in the document because they've been explicitly included. So I have the index file:
.. toctree::
:maxdepth: 2
pages/0010-foo
pages/0020-bar
In the file 0020-bar.rst, I'm specifically including a number of other files, as in:
.. contents:: :local:
.. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst
But when I build the project, I still get a warning that 0070-baz.rst isn't in any toctree, as in:
/home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn't included in any toctree
The weird thing is that I can see the content in the output. Is this normal? Does this warning always appear for files that are explicitly included rather than included via toctree?
If you only want to ..include:: a document in another document, without having it appear in any toctree.
Add :orphan: to the top of your document to get rid of the warning.
This is a File-wide metadata option. Read more from the Sphinx documentation.
Sphinx will complain about this whether the file is included or not.
However, you can specifically exclude files by using the exclude_patterns config value.
So for your case you might try to change Sphinx's conf.py file with something like:
exclude_patterns = ['pages/reference-architecture', 'some/other/file.txt']
You can exclude individual files, directories, or use file globbing patterns to match groups of files this way.
EDIT: See: Joakim's answer for another option that was added after this answer was created.
I had a situation where I couldn't edit the documents I wanted to be brought in as a git submodule. The documents already had their own structure including TOC page written in Markdown and I did want them to be processed by sphinx for consistency of formatting.
What I found I could do is specify a hidden toctree to make toctree aware of the documents, but not clutter up the toctree or add a bunch of errors to my sphinx build output.
* :doc:`Additional Book <external/index>`
.. toctree::
:hidden:
external/documentA.md
external/documentB.md
Indentation worked:
toctree::
:maxdepth: 2
hello <h.rst>
abc <your.rst>