Skip to content
Bash script to quickly add Sphinx capabilities to a project.
Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
tests
.gitignore
.gitlab-ci.yml
.gitmodules
.readthedocs.yml
.travis.yml
LICENSE
README.rst
docthis.sh
testme.sh

README.rst

docthis

pipeline

travis

readthedocs

Bash script to quickly add Sphinx capabilities to a project.

It aims to provide an easy and quick way to start writing Sphinx documentation.

docthis

Full documentation on Readthedocs.

Source code on:

Github.

Gitlab.

Part of:

doombots

Ingredients

ingredients

Contents

API Contents

Description

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
├── docs
│   ├── requirements.txt
│   └── source
│       ├── author
│       ├── compatibility
│       ├── conf.py
│       ├── description
│       ├── index
│       ├── license
│       ├── links
│       ├── requirements
│       ├── _static
│       ├── _templates
│       ├── usage
│       └── variables
├── 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.

Usage

Download the script, give it execution permissions and execute it:

wget https://raw.githubusercontent.com/constrict0r/docthis/master/docthis.sh
chmod +x docthis.sh
./docthis.sh -h

To run tests:

cd docthis
chmod +x testme.sh
./testme.sh

On some tests you may need to use sudo to succeed.

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 docs/source/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
  • 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.
  • 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|

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

Coverage Config

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/"

gh_cover_url = gh_cover_base_url + author + "/" + 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 + ">`_.",
}

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

Coverage 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 Conf

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 Conf

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

Parameters

The following parameters are supported:

help

  • -h (help): Show help message and exit.
./docthis.sh -h

path

  • -p (path): Optional path to project root folder.
./docthis.sh -p /home/username/my-project

Compatibility

License

MIT. See the LICENSE file for more details.

Links

UML

Main

The project data flow is shown below:

main

Author

author

The travelling vaudeville villain.

Enjoy!!!

enjoy

API

Scripts

docthis-sh

Generate Sphinx documentation.

Globals

PROJECT_PATH

Path to the project used as the source to generate documentation, if not specified the current path will be used.

Functions

escape()

Escape especial characters.

The escaped characters are:

  • Period.
  • Slash.
  • Double dot.
Parameters:$1 (str) – Text to escape.
Returns:The escaped input.
Return type:str

generate()

Setup sphinx and generate html and rst documentation.

Parameters:$1 (str) – Optional project path. Default current directory. $2 (str) – Optional CI service to use for generating a coverage badge.
Returns:0 if successful, 1 on failure, generates README-single rst on project’s root directory.
Return type:int

generate_rst()

Shows help message.

Parameters:$1 (str) – Optional project path. Default current directory. $2 (str) – Optional CI service to use for generating a coverage badge.
Returns:0 if successful, 1 on failure.
Return type:int

get_author()

Get the author’s name.

Parameters:$1 (str) – Optional project path. Default current directory.
Returns:0 if successful, 1 on failure, echo author’s name.
Return type:str

get_gitlab_ci_url()

Get the continuous integration repository URL for Gitlab.

Parameters:$1 (str) – Optional project path. Default current directory.
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) – Optional project path. Default current directory.
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) – Optional project path. Default current directory.
Returns:0 if successful, 1 on failure, echo Gitlab.
Return type:str

get_img_url()

Get the images repository URL.

Parameters:$1 (str) – Optional project path. Default current directory.
Returns:0 if successful, 1 on failure, echo images repository URL.
Return type:str

get_parameters()

Get bash parameters.

Accepts:

  • h (help).
  • p <path> (project_path).
Parameters:$@ (str) – Bash arguments.
Returns:0 if successful, 1 on failure. Set globals $PROJECT_PATH.
Return type:int

get_project()

Get project name.

Parameters:$1 (str) – Optional project path. Default current directory.
Returns:0 if successful, 1 on failure, echo project name.
Return type:int

get_travis_ci_url()

Get the continuous integration repository URL for Travis.

Parameters:$1 (str) – Optional project path. Default current directory.
Returns:0 if successful, 1 on failure, echo Travis CI URL.
Return type:str

get_variable()

Get a variable from the configuration file.

Parameters:$1 (str) – Required variable name. $2 (str) – Optional project path. Default current directory.
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) – Optional project path. Default current directory.
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) – Optional project path. Default current directory.
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) – Optional project path. Default current directory.
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: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.

This function assumes:

  • The author is the current user running the script.
  • A travis-ci enviroment exists for the current
    component.
  • An images repository exists the current user/project.

See this example.

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
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:

  • Remove unnecesary slashes.
  • Trim.
Parameters:$1 (str) – Text to sanitize.
Returns:The sanitized input.
Return type:str
You can’t perform that action at this time.