readthedocs build fails to produce sphinx documentation with shields.io svg badges - python-sphinx

My latest Sphinx documentaion fails when trying to build it with readthedocs. It has apperently something to do with the fact that I am trying to incorporate some badges from https://shields.io/. These badges are .svg graphic files.
I probably need to do some tweaking in my conf.py file?
On my local machine, I am able to produce the Sphinx documentation and all HTML files do look OK.
Here's an excerpt of my conf.py file:
# -- 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 = [
"nbsphinx",
"numpydoc",
"sphinx.ext.autodoc",
"sphinx_copybutton",
"sphinx.ext.napoleon",
]
napoleon_google_docstring = False
napoleon_numpy_docstring = True
numpy_validation_checks = {all}
# 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 = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_rtd_theme"
# 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 = []
Here's the text output: https://readthedocs.org/api/v2/build/17082650.txt

Although you may have disabled the epub and PDF builds in the RTD UI, you must take note in the RTD UI under Advanced Settings > Default settings:
These settings can be configured using a configuration file. That's the recommended way to set up your project. Settings listed here are ignored when using a configuration file.
Therefore you must be using a configuration file that enables both pdf and epub builds. Lo and behold:
https://github.com/andreas-vester/df2img/blame/3ba6e046c8d30ab3896b23835513740bd5aa97fa/.readthedocs.yaml#L12-L14
formats:
- pdf
- epub

Related

my sphinx rtd themed documentation builds locally, fails building when posting to rtd?

OH GEEZ
the extension is "myst**_**parser" and the library is myst-parser. The only thing better would be if somewhere else I had written mystParser...
Thank you
Steve - I don't use StackOverflow a lot. Is there something I need to do to recognize? that you provided the answer?
Add myst_parser to reqirements.txt. –
Steve Piercy
5 hours ago
sphinx-autobuild works great locally. I send my project to github with sphinx documentation (as .md files) within the /docs folder. Post to RTD web site. Fails. myst-parser is in requirements.txt.?
sphinx.errors.ExtensionError: Could not import extension myst_parser (exception: No module named 'myst_parser')
.readthedocs.yaml
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
tools:
python: "3.9"
# You can also specify other tool versions:
# nodejs: "16"
# rust: "1.55"
# golang: "1.17"
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
# formats:
# - pdf
# Optionally declare the Python requirements required to build your docs
python:
install:
- requirements: docs/requirements.txt
reqirements.txt
alabaster==0.7.12
Babel==2.11.0
bleach==5.0.1
build==0.9.0
certifi==2022.9.24
cffi==1.15.1
charset-normalizer==2.1.1
colorama==0.4.6
commonmark==0.9.1
cryptography==38.0.4
docopt==0.6.2
docutils==0.17.1
idna==3.4
imagesize==1.4.1
importlib-metadata==5.1.0
influxdb==5.3.1
jaraco.classes==3.2.3
jeepney==0.8.0
Jinja2==3.1.2
keyring==23.11.0
livereload==2.6.3
markdown-it-py==2.1.0
MarkupSafe==2.1.1
mccabe==0.7.0
mdit-py-plugins==0.3.1
mdurl==0.1.2
more-itertools==9.0.0
msgpack==1.0.4
myst-parser==0.18.1
packaging==21.3
paho-mqtt==1.6.1
pep517==0.13.0
pipreqs==0.4.11
pkginfo==1.9.1
pycodestyle==2.10.0
pycparser==2.21
pyflakes==3.0.1
Pygments==2.13.0
pyparsing==3.0.9
python-dateutil==2.8.2
pytz==2022.6
PyYAML==6.0
readme-renderer==37.3
requests==2.28.1
requests-toolbelt==0.10.1
rfc3986==2.0.0
rich==12.6.0
SecretStorage==3.3.3
six==1.16.0
snowballstemmer==2.2.0
Sphinx==5.3.0
sphinx-autobuild==2021.3.14
sphinx-rtd-theme==1.1.1
sphinx_design==0.3.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
tomli==2.0.1
tornado==6.2
twine==4.0.1
typing_extensions==4.4.0
urllib3==1.26.13
webencodings==0.5.1
yarg==0.1.9
zipp==3.11.0
conf.py
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
import os
import sys
# Add the code path
sys.path.insert(0, os.path.abspath('../code'))
project = 'GrowBuddies'
copyright = '2022, HappyDay'
author = 'HappyDay'
release = '2022.12.0'
# ignore files
exclude_patterns = ["py_env/*", '**/_*']
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = ['sphinx.ext.autodoc', 'myst-parser', 'sphinx.ext.autosectionlabel', 'sphinx_design']
# Make sure the target is unique
autosectionlabel_prefix_document = True
# Include methods that start with an _
napoleon_include_private_with_doc = True
# Add Myst extensions
myst_enable_extensions = ["colon_fence", "html_image"]
# Needed for font awesome support using the sphinx-design extension.
html_css_files = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
]
# Ignore documentating these files.
autodoc_mock_imports = ['influxdb', 'paho']
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
myst-parser is the name of the Python package. However, the name of the Python module once installed is myst_parser. You need to specify myst_parser in conf.py (not myst-parser).

Unable to authenticate with Confluence server for Sphinx documentation

I am using sphinx for building documentation in confluence.I am able to make html file using sphinx. But when I am trying to connect confluence using the "make confluence" command it's throwing an error
I checked by changing the confluence password and checked using API token still getting the error and unable to connect with confluence.
Ref link-
https://github.com/Shravankumarhiregoudar/sphinxDocumentation
conf.py file:
# 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.append('/home/4px/sphinx/scripts/')
# -- Project information -----------------------------------------------------
project = 'sites'
copyright = '2021, divyank'
author = 'divyank'
# -- 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.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'sphinxcontrib.confluencebuilder'
]
confluence_publish = True
confluence_space_name = 'Documentation'
##confluence_ask_password = True
#confluence_parent_name = 'API Documentation'
# (for Confluence Cloud)
confluence_server_url = 'https://<....>.atlassian.net/wiki/spaces'
confluence_server_user = '<....>'
confluence_server_pass = '<.......>'
# (or, for Confluence Server)
#confluence_server_url = 'https://intranet-wiki.example.com/'
#confluence_server_user = 'myawesomeuser'
# 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=[]
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'default'
# 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']
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
'preamble': '',
# Latex figure (float) alignment
'figure_align': 'htbp',
}
Error:
WARNING: normalizing confluence url from https://<......>.atlassian.net/wiki/ to https://<.......>.atlassian.net/wiki/
sphinxcontrib.confluencebuilder error:
---
Unable to authenticate with the Confluence server.
Ensure your username and password are correct. If your username and password is correct, you may need to unlock your Confluence account be re-logging in with your browser or asking your Confluence administrator for help.
---
make: *** [confluence] Error 2
I am able to resolve this issue using API token in the confluence password field in conf.py file.
How to generate API token-
Manage API tokens for your Atlassian account
Ref link-
Unable to authenticate with the Confluence server using sphinxcontrib.confluencebuilder

How to import Markdown with Sphinx and myst-parser into Readthedocs?

In my docs/source/conf.py I have this code:
extensions = [
"sphinx.ext.autodoc",
"myst_parser",
]
source_suffix = ['.rst', '.md']
All my files are in Markdown, not in reStructuredText.
On ReadTheDocs, the initial build was successful technically, only until the modules page was "not found" and the index page is completely blank.
My .readthedocs.yaml:
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
# Optionally build your docs in additional formats such as PDF
formats: all
# Optionally set the version of Python and requirements required to build your docs
python:
version: "3.8"
install:
- method: pip
path: .
extra_requirements:
- docs
My setup.cfg contains this:
[options.extras_require]
docs =
sphinx
myst-parser
Of course, doing make clean html in docs/ works completely fine. Not sure why ReadTheDocs cannot properly link to the rest of the.md files from index.md.
I solved it. I checked the build logs, turns out I have some syntax errors (I did list[str] not List[str] with from typing import List)

How to change images path when converting AsciiDoc file containing diagrams to html using Asciidoctor Ruby API?

Lets suppose there is a web based documentation available at docs.project
Directory structure
/ - project root
/docs - documentation files in asciidoc format
index.adoc - documentation entry point
/public - public directory
generate.rb
Desirable workflow
I change documentation source in /docs directory.
I commit and push changes.
When pushing, the server runs ruby <project_root>/generate.rb command that rewrites the html presentation of the documentation.
index.adoc
= Documetation
Some text
[plantuml]
....
Client --> Server: Request
Server --> Client: Response
....
generate.rb
require 'asciidoctor'
require 'asciidoctor-diagram'
ROOT = File.dirname(__FILE__)
entry = ROOT + '/docs/index.adoc'
outdir = ROOT + '/public'
Asciidoctor.convert_file entry, to_dir: outdir, mkdirs: true
Problem
Current generate.rb script puts index.html file in public while images go to docs thus they are not available when you open docs.project in browser.
How to specify the images path?
You can use imagesdir
You could move all your images that are being used in your index.adoc into the public folder(since this is your output folder) and can set imagesdir document attribute like:
:imagesdir: ../public/
inside your index.adoc file. You could learn more about imagesdir here
Your problem should be that when using the Ruby API, the default safe mode is set to :secure, which should prevent access to files which reside outside of the parent directory of the source file. I am assuming to_dir is allowed to write the file, while plantuml goes through a different generation process (probably initially generates the image and then includes it, preventing access to the directory). In any case, you have two options.
Use unsafe mode with:
Asciidoctor.convert_file entry, to_dir: outdir, mkdirs: true, safe: :unsafe
It is probably not the best solution, use only if you are running it with controlled content (and no one can put something like include::/etc/passwd[] in the adoc source).
Change the base_dir with:
Asciidoctor.convert_file entry, base_dir: '.', to_dir: outdir, mkdirs: true
Which should work, assuming your directory structure looks like:
.
├── docs
│   └── index.adoc
├── generate.rb
└── public

MoinMoin seperate theme folder from MoinMoin htdocs folder

I'd like to seperate my custom theme folder from the default MoinMoin htdocs folder. Here is my directory structure of my current installation:
/path/to/python2.7/lib/site-packages/MoinMoin/web/static/htdocs/
/path/to/python2.7/lib/site-packages/MoinMoin/web/static/htdocs/...
/path/to/python2.7/lib/site-packages/MoinMoin/web/static/htdocs/index.html
/path/to/python2.7/lib/site-packages/MoinMoin/web/static/htdocs/classic
/path/to/python2.7/lib/site-packages/MoinMoin/web/static/htdocs/modern
/path/to/python2.7/lib/site-packages/MoinMoin/web/static/htdocs/mytheme
/path/to/python2.7/lib/site-packages/MoinMoin/web/static/htdocs/mytheme/style.css
And my custom Git-versioned wiki/data directory:
/path/to/git-repo/wikiconfig.py
/path/to/git-repo/wikiserver.py
/path/to/git-repo/wiki/data/...
/path/to/git-repo/wiki/data/plugin/theme/mytheme.py
/path/to/git-repo/wiki/underlay/...
The wikiconfig.py contains the following configuration:
class LocalConfig(multiconfig.DefaultConfig):
wikiconfig_dir = os.path.abspath(os.path.dirname(__file__))
instance_dir = os.path.join(wikiconfig_dir, 'wiki')
data_dir = os.path.join(instance_dir, 'data', '') # path with trailing /
data_underlay_dir = os.path.join(instance_dir, 'underlay', '') # path with trailing /
DesktopEdition = True # give all local users full powers
acl_rights_default = u"All:read,write,delete,revert,admin"
surge_action_limits = None # no surge protection
sitename = u'Foo'
logo_string = u'<span><img src="...">Bar</span>' % url_prefix_static
page_front_page = u'StartPage'
theme_default = 'mytheme'
I would like to move the theme's static files to the /path/to/git-repo folder, because this directory is a Git repository which should contain all custom modifications, and also the theme's static files.
Any ideas how this could be done?
Regards
I suggest you just leave the builtin static stuff where it is.
What you can do for custom and separate theme development is to serve your static stuff at some specific URL and catch that URL in the web server before it gets given to moin.wsgi (and ends up being served by MoinMoin's builtin static file server), something like:
Alias /moin_static196/mytheme /path/to/git-repo/static
WSGIScriptAlias / /..../moin.wsgi
/moin_static196 is the url path moin 1.9.6 uses by default, you can modify it in wikiconfig.py to use anything you like.
You would put the theme python code also into your git repo and just symlink it from the instances data/plugin/theme/ directory.

Resources