Skip to main content

Tool for generating a json file with the name and url of versions.

Project description

https://img.shields.io/appveyor/ci/SteinwurfApS/versjon/master.svg?style=flat-square&logo=appveyor https://travis-ci.org/steinwurf/versjon.svg?branch=master

What it is:

  • A tool for linking multiple versions of your project’s Sphinx documentation, without the need for special services such as readthedocs.org.
  • Useful if you build and host your documentation as a static site.

How it works:

  • versjon works by injecting some basic HTML in to the generated documentation.

Demonstration

demo.gif

Installation

  1. Install the versjon tool using pip:

    python -m pip install versjon
    

Building the docs

  1. Build all the different versions of your documentation into a common directory. For example generating all the docs in the site directory:

    git checkout 2.0.0
    sphinx-build... -D version=2.0.0 ... site/build_2.0.0
    
    ...
    
    git checkout 5.1.1
    sphinx-build... -D version=5.1.1 ... site/build_5.1.1
    

    versjon will use whatever version is specified in the Sphinx configuration: https://www.sphinx-doc.org/en/master/usage/configuration.html If you have the specified the version number in conf.py you can omit the -D version option to Sphinx build.

  2. Run versjon in the common directory - and you are done.

Index page

As default versjon will generate an index.html file with a redirect to the latest stable version, or if no semver version exists the first branch, presumably the master. You can disable this behavior with --no-index option.

Stable index

As default versjon will generate a folder in the documentation root called stable. This folder will contain an index.html with a redirect to the latest stable version. You can disable this behavior with --no-stable-index option.

Built in templates (injection)

versjon ships with a couple of built-in templates, that get injected in the generated HTML:

  • head.html: This template gets injected into the <head> tag of the generated HTML pages. In this template you have access to the following variables: general, build, page.
  • header.html: This template is inject at the beginning of the <body> tag. In this template you have access to the following variables: general, build, page.
  • footer.html: This template is inject at the end of the <body> tag. In this template you have access to the following variables: general, build, page.
  • index.html: This template is use to generate an index.html in the root folder. In this template you have access to the following variables: general, page.
  • stable_index.html: This template is use to generate an index.html in the stable folder. In this template you have access to the following variables: general, page.

Customization

You can provide you own template for generating the version selector etc.

The easiest way is probably to copy one of the default HTML templates, e.g., src/templates/footer.html one and adapt it.

If you want to “inject” a custom footer. Create a file called footer.html and put it somewhere in your project, e.g., mydocs/footer.html now invoke versjon with the --user_templates argument, e.g.,:

./versjon --user_templates=mydocs

verjson will prioritize finding templates in the users path first. If none is found it will fallback to the built-in.

If you want to disable a built-in template, simply create an empty file with the same name as the template you want to disable e.g. header.html if the template is empty no content will be injected.

The context

In the templates you can access the information gathered by versjon. Based on this you can generate the needed HTML.

The following lists the various variables.

General variables

  • semver: A list of versions with valid sematic version numbers.
  • other: A list of versions with non-semantic version numbers. Typically this list will contain branches etc.
  • stable: If we have any semantic version releases the stable version will be the newest release in the semver list.
  • docs_path: Dictionary mapping versions to the build folder for a version relative to the documentation root.

Build variables

  • current: The current version
  • is_semver: True if the current version follows semantic versioning

Page variables

  • page_root: Relative path to the documentation root from a given HTML page. Concatenating the page_root with a path in docs_path will give a valid relative link from one HTML page to the root folder of specific version.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for versjon, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size versjon-1.1.0-py2.py3-none-any.whl (9.5 kB) File type Wheel Python version py2.py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page