Bash script to quickly add Sphinx capabilities to a project.
It aims to provide an easy and quick way to start writing Sphinx documentation.
Full documentation on Readthedocs.
Source code on:
Ingredients
Bash script to quickly add Sphinx capabilities to a project.
It aims to provide an easy and quick way to start writing Sphinx documentation.
When runned for first time on a new project folder, this script setups Sphinx, creates new source files and generates documentation from that sources. When the sources already exists this script only generates documentation without adding any file.
Assuming the current directory is named example, the generated directory layout is shown below:
example ├── doc │ ├── requirements.txt │ └── source │ ├── author │ ├── compatibility │ ├── conf.py │ ├── description │ ├── index │ ├── license │ ├── links │ ├── requirement │ ├── _static │ ├── _templates │ ├── usage │ └── variable ├── docthis.sh ├── README └── .readthedocs.yml
Additionally to the documentation generated using the standard html and rst Sphinx builders, a single rst file named README-single is created on the project’s root folder.
Download the script, give it execution permissions and execute it:
wget https://gitlab.com/constrict0r/docthis/raw/master/docthis.sh chmod +x docthis.sh ./docthis.sh
This scripts reads the conf.py file to generate the README-single file, you can control how to generate the documentation on this file.
The folder doc/build/rst/ generated by Sphinx is used as the sources to construct the file README-single.
When generating a README-single file, this script handles the images found on the rst sources specially: Using the alt attribute of each image, the script constructs an URL for each found image and insert it on the final README-single file.
Each alt attribute must correspond to each image name without the extension, for example if the image name is author.png, then the alt attribute of the image on the rst file must be the text author:
.. image:: author.png :alt: author
This applies also for the images defined as variables or global substitutions on the conf.py file:
author_img = ".. image:: " + img_url + "author.png\n :alt: author"
global_substitutions = {
"AUTHOR_IMG": author_img,
"MAIN_IMG": ".. image:: " + img_url + "main.png\n :alt: main",
}
When the image filename is composed by more than one word, it is recommended to use underscore to separate each pair of words in the name, for example variable_empty.png.
The images with the alt attribute setted to:
- coverage
- coverage_gitlab
- github_ci
- pipeline
- travis
- readthedocs
Will be treated specially, for each one of them, a badge image will be inserted on place:
- coverage: A Python coverage badge using Coveralls.
- coverage_gitlab: A Python coverage badge using Gitlab.
- github_ci: A Github-CI badge.
- pipeline: A Gitlab-CI badge.
- travis: A Travis-CI badge.
- readthedocs: A Readthedocs badge.
This scripts searches for an img_url variable on the conf.py file, if it exists, is used for the images replacement:
img_url = "https://raw.githubusercontent.com/author/project/img/master/"
To comply with pep8, it is recommended to split the img_url variable on multiple parts by specifying the variable img_base_url, if you are using Github to host your images (which is the default), you can add to conf.py the following configuration:
img_base_url = "https://raw.githubusercontent.com/" img_url = img_base_url + author + "/" + project + "/img/master"
If you use Gitlab, then add the following configuration to the conf.py file:
img_base_url = "https://gitlab.com/" + author + "/" + project + "/" img_url = img_base_url + "raw/master/img/"
If the img_url variable does not exists, the default value used is:
img_url = "https://raw.githubusercontent.com/author/project/img/master/"
Once the img_url variable is set, you can add images to the global_substitutions section on the conf.py file:
global_substitutions = {
"MAIN_IMG": ".. image:: " + img_url + "main.png\n :alt: main",
}
As you can see the image name must match the alt attribute (main without the .png extension).
Once you added images to global_subtitutions, you can use the substitutions on a rst source file:
My UML ------ |MAIN_IMG|
If you want to use only local images (don’t use a image repository), configure your img_url like this:
img_url = '../../img/'
This scripts searches for a github_url variable on the conf.py file, if it exists, is used for the Github link replacement:
github_url = "https://github.com/author/project"
To comply with pep8, it is recommended to split the github_url variable on multiple parts by specifying the variable github_base_url.
github_base_url = "https://github.com/" github_url = github_base_url + author + "/" + project
Once the github_url variable is set, you can add the variable GITHUB_LINK to the global_substitutions section on the conf.py file:
global_substitutions = {
"GITHUB_LINK": "`Github repository <" + github_url + ">`_.",
}
This scripts searches for a github_ci_url variable on the conf.py file, if it exists, is used for the Gitlab CI badge replacement:
github_ci_url = "https://github.com/author/project/workflows/CI"
Or
github_ci_url = github_url + "/workflows/CI"
Once the github_ci_url variable is set, you can add the variable GITHUB_CI_LINK to the global_substitutions section on the conf.py file:
global_substitutions = {
"GITHUB_CI_LINK": "`Github CI <" + github_ci_url + ">`_.",
}
This scripts searches for a gh_cover_url variable on the conf.py file, if it exists, is used for the coverage badge (using Github) replacement:
gh_cover_url = "https://coveralls.io/repos/github/author/project/badge.svg"
To comply with pep8, it is recommended to split the gh_cover_url variable on multiple parts by specifying the variable gh_cover_base_url.
gh_cover_base_url = "https://coveralls.io/repos/github/" + author + "/" gh_cover_url = gh_cover_base_url + project + "/badge.svg"
You will also need to add the variable COVERAGE_GITHUB_BADGE to the global_substitutions section on the conf.py file:
global_substitutions = {
"COVERAGE_GITHUB_BADGE": ".. image:: " + gh_cover_url
+ "\n :alt: coverage",
}
This scripts searches for a gitlab_url variable on the conf.py file, if it exists, is used for the Gitlab link replacement:
github_url = "https://gitlab.com/author/project"
To comply with pep8, it is recommended to split the gitlab_url variable on multiple parts by specifying the variable gitlab_base_url.
gitlab_base_url = "https://gitlab.com/" gitlab_url = gitlab_base_url + author + "/" + project
Once the gitlab_url variable is set, you can add the variable GITLAB_LINK to the global_substitutions section on the conf.py file:
global_substitutions = {
"GITLAB_LINK": "`Gitlab repository <" + gitlab_url + ">`_.",
}
This scripts searches for a gitlab_ci_url variable on the conf.py file, if it exists, is used for the Gitlab CI badge replacement:
gitlab_ci_url = "https://gitlab.com/author/project/pipelines"
Or
gitlab_ci_url = gitlab_url + "/pipelines"
Once the gitlab_ci_url variable is set, you can add the variable GITLAB_CI_LINK to the global_substitutions section on the conf.py file:
global_substitutions = {
"GITLAB_CI_LINK": "`Gitlab CI <" + gitlab_ci_url + ">`_.",
}
This scripts searches for a gl_cover_url variable on the conf.py file, if it exists, is used for the coverage badge (using Gitlab) replacement:
gl_cover_url = "https://gitlab.com/author/project/badges/master/coverage.svg"
To comply with pep8, it is recommended to split the gl_cover_url variable on multiple parts by specifying the variable gl_cover_base_url.
gl_cover_base_url = "https://gitlab.com/" + author + "/" + project gl_cover_url = gl_cover_base_url + "/badges/master/coverage.svg"
You will also need to add the variable COVERAGE_GITLAB_BADGE to the global_substitutions section on the conf.py file:
global_substitutions = {
"COVERAGE_GITLAB_BADGE": ".. image:: " + gl_cover_url
+ "\n :alt: coverage_gitlab",
}
This scripts searches for a travis_url variable on the conf.py file, if it exists, is used for the Travis CI badge and link URL replacements:
travis_url = "https://travis.org/author/project"
To comply with pep8, it is recommended to split the travis_url variable on multiple parts by specifying the variable travis_base_url.
travis_base_url = "https://travis-ci.org/" travis_url = travis_base_url + author + "/" + project
Once the travis_url variable is set, you can add the variables TRAVIS_BADGE and TRAVIS_LINK to the global_substitutions section on the conf.py file:
global_substitutions = {
"TRAVIS_BADGE": ".. image:: " + travis_url + ".svg\n :alt: travis",
"TRAVIS_LINK": "`Travis CI <" + travis_url + ">`_."
}
This scripts searches for a readthedocs_url variable on the conf.py file, if it exists, is used for the Readthedocs badge and link URL replacements:
readthedocs_url = "https://" + project + ".readthedocs.io"
Once the readthedocs_url variable is set, you can add the variables READTHEDOCS_BADGE and READTHEDOCS_LINK to the global_substitutions section on the conf.py file:
global_substitutions = {
"READTHEDOCS_BADGE": ".. image:: https://rtfd.io" + readthedocs_badge,
"READTHEDOCS_LINK": "`readthedocs <" + readthedocs_url + ">`_.",
}
The following parameters are supported:
- -x (python executable): This parameter can only take the values
python or python3, and indicates wich executable to use when running python tasks.
If python3 is available, this parameter defaults to python3, otherwise python is used.
./docthis.sh -x python3
- -h (help): Show help message and exit.
./docthis.sh -h
- -p (path): Optional path to project root folder.
./docthis.sh -p /home/username/my-project
- -i (install requirements): Install all requirements.
./docthis.sh -i
- Bash.
MIT. See the LICENSE file for more details.
The project data flow is shown below:
The Travelling Vaudeville Villain.
Enjoy!!!
Generate documentation with Sphinx, from root run: ./docthish.sh.
PROJECT_PATH
Path to the project used as source, defaults to current path.PYTHON_EXEC
Python executable to use: python or python3. Empty by default.INSTALL_REQUIREMENT
Install requirements or not.
error_message()
Shows an error message.
Parameters: $1 (str) – Error name: custom, execution, path, sudo, <name>. $2 (str) – Optional text to use on error messages. Returns: 0 if successful, 1 on failure. Return type: int escape()
Escape especial characters.
The escaped characters are:
- Period.
- Slash.
- Colon.
Parameters: $1 (str) – Text to escape. Returns: The escaped input. Return type: str generate()
Setup Sphinx and generate html and rst documentation, generates a single README-single file that can be used on github or gitlab.
Parameters: $1 (str) – Optional project path. Default to current path. $2 (str) – Optional CI service to use for generating a coverage badge. Returns: 0 if successful, 1 on failure, generates README-single file on project’s root directory. Return type: int generate_rst()
Generate rst documentation using sphinx.
This function will extract each filename to include from the index file and concatenate all files into a single README-single file.
- This function assumes:
- The project has a file structure as created by generate().
- The index file contains the toctree directive.
Parameters: $1 (str) – Optional project path. Default to current path. $2 (str) – Optional CI service to use for generating a coverage badge. Returns: 0 if successful, 1 on failure, generates README-single file on project’s root directory. Return type: int get_author()
Get the author’s name.
Parameters: $1 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo author’s name. Return type: str get_doc_path()
Obtains the project’s documentation directory.
This function tries:
- Read a .readthedocs.yml file.
- Search for the ./docs directory.
- Default to ./doc directory.
Parameters: $1 (str) – Optional project path. Default to current path. Returns: 0 if successful, 1 on failure, echo path to the documentation directory. Return type: str get_gitlab_ci_url()
Get the continuous integration repository URL for Gitlab.
If the URL cannot be found, then a default URL is returned.
- This function assumes:
- The project has a file structure as created by generate().
Parameters: $1 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo Gitlab CI URL. Return type: str get_gh_cover_url()
Get the coverage badge URL for Github (coveralls).
Parameters: $1 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo Github coverage (coveralls) URL. Return type: str get_gl_cover_url()
Get the coverage badge URL for Gitlab.
Parameters: $1 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo Gitlab. Return type: str get_img_url()
Get the images repository URL.
If the URL cannot be found, then a default Github URL is returned.
- This function assumes:
- The project has a file structure as created by generate().
Parameters: $1 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo images repository URL. Return type: str get_parameters()
Get bash parameters.
Accepts:
- h (help).
- i (install requirements).
- p <project_path>.
- x <python_executable>.
Parameters: $@ (str) – Bash arguments. Returns: 0 if successful, 1 on failure. Set globals. Return type: int get_project()
Get the project’s name.
Parameters: $1 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo project’s name. Return type: int get_python_exec()
Obtains the Python executable to use: python or python3.
- This function tries:
- Use the $PYTHON_EXEC variable if not empty and like
- ‘python’.
- Use ‘python3’ if available.
- Use ‘python’ if available.
Parameters: No arguments. Returns: 0 if successful, 1 on failure, echo project’s name. Return type: int get_travis_ci_url()
Get the continuous integration repository URL for Travis.
If the URL cannot be found, then a default URL is returned.
- This function assumes:
- The project has a file structure as created by generate().
Parameters: $1 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo Travis CI URL. Return type: str get_variable()
Get a variable from the configuration file.
- This function assumes:
- The project has a file structure as created by generate().
Parameters: $1 (str) – Required variable name. $2 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo variable value. Return type: str get_variable_from_conf()
Get a raw variable from the configuration file.
Parameters: $1 (str) – Required variable name. $2 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo variable value. Return type: str get_variable_from_conf()
Get a raw variable from the configuration file.
Parameters: $1 (str) – Required variable name. $2 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo variable value. Return type: str get_variable_line()
Get a matching line from the configuration file.
Parameters: $1 (str) – Required variable name. $2 (str) – Path to the configuration file. Returns: 0 if successful, 1 on failure, echo variable value. Return type: str help()
Shows help message.
Parameters: Function has no arguments. Returns: 0 if successful, 1 on failure. Return type: str install_apt()
Installs Apt packages.
Parameters:
- $1 (str) – List of packages name to install, must be
space-separated.
Returns: 0 if successful, 1 on failure.
Return type: int
install_pip()
Installs Python packages via pip.
This function ensures that Python, Pip and Setuptools are installed and then installs all required packages.
You can pass to this function: - A filepath to a requirements*.txt file to be installed. - A filepath to directory containing requirements*.txt files to install. - A single package name.
If this function is called without passing any argument to it, it will search for requirements*.txt files on the to current path.
This function expects that each requirements filename has the text ‘requirements’ included on it and to have the .txt extension.
This functions will always check for Python, Pip and Setuptools to be installed and will try to install them if not present.
Each package will be checked to see if its installed, if not installed then this function proceeds to install it.
Parameters: $1 (str) – Optional file path or single package name. Returns: 0 if successful, 1 on failure. Return type: int main()
Generate documentation using sphinx.
Generates README-single rst on project’s root directory.
Parameters: $@ (str) – Bash arguments string. Returns: 0 if successful, 1 on failure. Return type: int readthedocs_to_rst()
Replace reference from readthedocs format to standard rst.
See this link for an example images repository.
Parameters: $1 (str) – Path to file where to apply replacements.
$2 (str) – Optional component name to use in replacements.
Returns: 0 if successful, 1 on failure, modifies passed file.
Return type: int
replace_tokens()
Given an input string, replaces the tokens:
- author
- project
- _url
- _link
- _badge
This function is recursive, this means that it will not stop replacing tokens until there is no token left.
Parameters: $1 (str) – Input text where to apply the substitutions. Returns: 0 if successful, 1 on failure, echo the resulting string. Return type: str sanitize()
Sanitize input.
The applied operations are:
- Trim.
- Remove unnecesary slashes.
Parameters: $1 (str) – Text to sanitize. Returns: The sanitized input. Return type: str trim()
Trim whitespace at the beggining and end of a string.
Parameters: $1 (str) – Text where to apply trim. Returns: The trimmed input. Return type: str validate()
Apply validations.
- The validation categories are:
- install: Verifies if the current user is capable of
- installed the given requirement.
- sudo: Verifies if the current user can obtain
- administrative permissions.
- package-name: Verifies if a specific package is installed
- via apt or pip.
This function assumes that everything that is not one of the categories is a package name.
Parameters: $1 (str) – A category or a package name. Returns: true if valid, false otherwise. Return type: str validate_apt
Determines if a package is installed via Apt.
Parameters: $1 (str) – The package name. Returns: true if installed via apt, false otherwise. Return type: str validate_pip
Determines if a package is installed via pip.
Parameters: $1 (str) – The package name. Returns: true if installed via pip, false otherwise. Return type: str validate_pip_installed()
Verifies if pip is installed.
Parameters: No arguments. Returns: true if installed, false otherwise. Return type: str