Introduction

Dox supports software developers to write requirements, architecture and software design for their projects. All specification elements can be linked to each other and to source code to get a full traceability.

Dox is the combination of the stand-alone Ruby gem dim and the three Python extensions for Sphinx dox_style, dox_util and dox_trace.

Overview

For the documentations of the individual tools, please click on the links below.

Tool Name	Description
dox_style	Provides a default configuration for Sphinx documentations. It also checks several style conventions.
dox_util	Collection of small convenience-features for Sphinx documentations.
dox_trace	Provides specification directives to achieve traceability in Sphinx documentations.
dim	A light-weight requirements tool based on YAML.

Changelog

See https://github.com/esrlabs/dox/blob/master/CHANGELOG.md.

Contributing

Contributions are welcome, please create pull requests! If you want to actively develop these tools, please contact the owners of https://github.com/esrlabs/dox.

To merge a pull request, two requirements must be fulfilled:

• A code-owner must approve the PR.

• The automatic checks must not report any error.

Release Steps

Note

This section is for the code-owners.

• Ensure that all relevant pull requests are merged and issues are closed.

• Increment the version.

  • Dim: <dox root>/dim/version.txt

  • Sphinx extensions: <dox root>/dox_*/dox_*/version.py

• Extend the change log.

  • Dim: <dox root>/dim/documentation/source/pages/changelog.rst

  • Sphinx extensions: <dox root>/dox_*/documentation/source/pages/changelog.rst

• Adapt the overall documentation in <dox root>/documentation.

• If applicable, update the README.md files:

  • Overall: <dox root>/README.md

  • Dim: <dox root>/dim/README.md

  • Sphinx extensions: <dox root>/dox_*/README.md

• Push and merge the changes to the master branch of https://github.com/esrlabs/dox with a pull request.

• Build the documentation. Go to <dox root>/documentation and type:

  make dist
  

• Push the output from <dox root>/documentation/build/html to the gh-pages branch of https://github.com/esrlabs/dox. Please do not delete the empty .nojekyll file, otherwise the HTML style sheets will not work correctly.

• Create the packages.

  • Dim: Go to <dox root>/dim and type:

    gem build dim.gemspec
    

    For more information about Ruby gems see https://guides.rubygems.org.

  • Sphinx packages: Go to <dox root>/dox_* and type:

    python -m build
    

    For more information about Python packages see https://packaging.python.org.

• Upload the packages (accounts and appropriate access rights are required).

  • Dim: Go to <dox root>/dim and type:

    gem push dim-toolkit-1.2.3.gem
    

  • Sphinx packages: Go to <dox root>/dox_* and type:

    python -m twine upload dist/*
    

• Add a new release tag and copy/paste the changelog entries to https://github.com/esrlabs/dox/tags.