I am trying to use todo feature, I found a link on sphinx-docs and the following syntax
.. todo::
but it says that I need to set the todo_include_todos to True, as by default it is False, which file I need to update to get in enabled?
I found another SO post Sphinx todo box not showing but don't think it mentions the file where I need to set the config.
sphinx.ext.todo is a Sphinx extension which can be enabled by adding it to the list of extensions in your conf.py:
extensions = [
'extname',
'sphinx.ext.todo',
]
Once enabled, you need to configure it by setting the value todo_include_todos to True, also in your conf.py:
# Display todos by setting to True
todo_include_todos = True
Theme support for todos varies.
See also http://www.sphinx-doc.org/en/stable/config.html#confval-extensions
Note that the configuration option can also be overridden on the command line, which may make it easier to quickly expose or hide "to do"s according to the target audience. I believe booleans have to be passed as 0 or 1 in this case...
sphinx-build -b html -D todo_include_todos=1 -c docs docs build/html
or
python -m sphinx -b html -D todo_include_todos=1 -c docs docs build/html
Related
I am trying to run a script to modify the documentation built by sphinx hosted by Read the Docs (because some links are not properly handled). The script works when I try to build it locally, but either fails on the Read the Docs build or the changes do not get propagated to the web site.
The script I'm trying to run is super simple, it replaces some html links that are not properly converted by sphinx-markdown-tables:
#!/bin/bash
# fix_table_links.sh
FILE="_build/html/api_reference.html"
if [[ "$1" != "" ]]; then
FILE="$1"
fi
sed -E 's/a href="(.*)\.md"/a href="\1\.html"/g' -i ${FILE}
My readthedocs.yml looks like this:
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# Optionally build your docs in additional formats such as PDF and ePub
formats: all
# Optionally set the version of Python and requirements required to build your docs
python:
install:
- requirements: docs/requirements.readthedocs.txt
build:
os: ubuntu-20.04
tools:
python: "3.8"
jobs:
post_build:
- echo "Running post-build commands."
- bash docs/fix_table_links.sh _readthedocs/html/api_reference.html
There are two cases:
Case 1) Using the readthedocs.yml as above, the build fails because _readthedocs/html/api_reference.html does not exist, despite this directory being the place the documentation claims will get uploaded from here. An example failure of this run is here.
Case 2) If I change the final of readthedocs.yml to bash docs/fix_table_links.sh docs/_build/html/api_reference.html, then the build passes (example here). But the links are not updated on the Read the Docs site: they still point to markdown pages rather than their corresponding HTML pages, so it must not be the version that gets uploaded to the Read the Docs web site.
Wading through documentation, I can't figure out how do this. Has anybody done this before or have a better grasp on how Read the Docs builds work? Thanks!
If you're willing to rewrite the script as a Python function, then you can do this super easily by connecting it as an event handler for the build-finished event.
I've done something similar in one of my own repos, except I post-process a .rst file. It's not actually used on RTD, but I can see it works in the build logs. So it should work to post-process your HTML files as well, since the build-finished event would occur after they've been generated.
First, define the script as a function in your conf.py. It needs to have app and exception as parameters.
def replace_html_links(app, exception):
with open(FILE, 'r') as f:
html = f.read()
# stuff to edit and save the html
Then either define or add to your setup function:
def setup(app):
app.connect('build-finished', replace_html_links)
And that's it!
How do I make a tag commit/push message show up as markdown on GitHub?
The closest I’ve seen is someone suggesting to make a custom script defining the “body”
#VonC, that is good where gh is available, however, I'm in an environment where it's not... as such, I created the following bash script using the api. (clearly all below $vars need to be either defined or substituted for working example)
COMMIT_BODY can be markdown (e.g. COMMIT_BODY="**This is markdow**")
res=`curl --user "$USERNAME:$TOKEN" -X POST https://api.github.com/repos/${ORGANIZATION}/${REPO}/releases \
-d "
{
\"tag_name\": \"$VERSION\",
\"target_commitish\": \"$BRANCH\",
\"name\": \"$VERSION\",
\"body\": \"$COMMIT_BODY\",
\"draft\": false,
\"prerelease\": false
}"`
You could try and use the GitHub CLI gh (after installation, and login), and its gh release create command in order to pass a markdown file as release notes.
gh release create v1.2.3 -F changelog.md
That would do it all: tag, message tag, release notes and publication of said release to GitHub.
Right from your local workstation/repository.
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.
Is it possibe to use Bash to add languages to Chromium? That is, do the equivalent of going to Settings - Advanced - Languages in the Chromium GUI, activate the languages you want, and then activate spell-checking for the same languages? Had a look at this, but there doesn't seem to be anything that fits the bill.
Figured it out. The best way seems to be to add a Python block to read and manipulate the Preferences-file using the JSON library. Before you do anything, you need to get your bearings in the Preferences-file. What are the relevant elements that you need to change?
If you go to Preferences in the Chromium GUI, you can see that there are two relevant settings:
1) Languages:
2) Dictionaries (for spell check):
These can be found in the Preferences-file by pretty-printing the file in the terminal (improving it with pygmentize) or saving a pretty-printed output to a file:
less Preferences | python -m json.tool | pygmentize -g
or
~/.config/chromium/Default$ less Preferences | python -m json.tool >> ~/Documents/output.txt
Searching through the file for language settings, you will find two relevant elements:
"intl": {
"accept_languages": "en-US,en,nb,fr-FR,gl,de,gr,pt-PT,es-ES,sv"
},
and
"spellcheck": {
"dictionaries": [
"en-US",
"nb",
"de",
"gr",
"pt-PT",
"es-ES",
"sv"
],
"dictionary": ""
}
Before you do anything else, it is wise to backup the Preferences-file... Next,you can alter the language settings by adding the following python-block to the bash script:
python - << EOF
import json
import os
data = json.load(open(os.path.expanduser("~/.config/chromium/Default/Preferences"), 'r'))
data['intl'] = {"accept_languages": "en-US,en,nb,fr-FR,gl,de,pt-PT,es-ES,sv"}
data['spellcheck'] = {"dictionaries":["en-US","nb","de","pt-PT","es-ES","sv"],"dictionary":""}
with open(os.path.expanduser('~/.config/chromium/Default/Preferences'), 'w') as outfile:
json.dump(data, outfile)
EOF
In this case, the script will remove Greek from the available languages and the spellchecker. Note that in order to add languages, you need to know the language code accepted by Chromium.
You can find more on reading and writing JSON here and here, and more on how to include Python scripts in bash scripts here.
When running pylint on a python file it shows me warnings regarding TODO comments by default. E.g.:
************* Module foo
W:200, 0: TODO(SE): fix this! (fixme)
W:294, 0: TODO(SE): backlog item (fixme)
W:412, 0: TODO(SE): Delete bucket? (fixme)
While I do find this behavior useful, I would like to know of a way of temporarily and/or permanently turn these specific warnings on or off.
I am able to generate a pylint config file:
pylint --generate-rcfile > ~/.pylintrc
I'm just note sure what to put in this file to disable warnings for TODO comments.
in the generated config file, you should see a section
[MISCELLANEOUS]
# List of note tags to take in consideration, separated by a comma.
notes=FIXME,XXX,TODO
simply drop TODO from the "notes" list.
The config file is found at
~/.pylintrc
If you have not generated the config file, this can be done with
pylint --generate-rcfile > ~/.pylintrc
Along with the solution posted by #sthenault where you could disable all warnings, Pylint also allows you to ignore a single line (helpful if you would want to deal with it in the future) like so:
A_CONSTANT = 'ugh.' # TODO: update value # pylint: disable=fixme
or by stating the Rule ID:
A_CONSTANT = 'ugh.' # TODO: update value # pylint: disable=W0511
IMHO your code should not have # TODO but during development it might be needed to have TODO for a short period of time and in this case pylint will bother you. To avoid this during this time the best is to globally disable it in the pylintrc by adding fixme to the disable list like this:
[MESSAGES CONTROL]
# globally disable pylint checks (comma separated)
disable=fixme,...
So it let you the time to fix all your TODO and once this is done, you can remove the fixme from the pylintrc. Note if you use an older pylint version you will need to use W0511 instead of fixme. For more detail see https://pylint.pycqa.org/en/stable/technical_reference/features.html#messages-control-options
Changing the pylintrc notes as proposed in the first answer is a bad practice in my opinion. notes is designed to configure wich comments triggers the fixme warning and not designed to disable the warning.
In our projects we have a pylint.cfg file. We use the --rcfile pylint option to point to that file.
In pylint.cfg, I can disable checker W0511, which is the checker that complains about "TODO" and similar terms in comments. Just add W0511 to the comma-separated list for parameter disable.
But remember that, as Uncle Bob Martin says, a TODO is not an excuse to leave bad code in the system, and the code should be scanned regularly to remove TODOs, and pylint and/or sonarqube issues can work as good reminders and motivation for doing so.