Configuration

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.

Images

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|

Local Config

If you want to use only local images (don’t use a image repository), configure your img_url like this:

img_url = '../../img/'

Github Config

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 + ">`_.",
}

Github CI Config

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 + ">`_.",
}

Github Cover Conf

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",
}

Gitlab Config

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 + ">`_.",
}

Gitlab CI Config

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 + ">`_.",
}

Gitlab Cover Conf

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",
}

Travis CI Config

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 + ">`_."
}

Readthedocs Config

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 + ">`_.",
}