Welcome to documentation’s Documentation

To provide a quick setup guide for a documenting/creating a development environment.

The objective of this guide is to document creating an initial development environment, with a minimal set of programs.

Once the baseline has been established, the, now available programs can be used to create an initial python documentation project, containing a source package docs. This will then become a template based repository, that combined with a sparse checkout, can inherit common configurations throughout all your projects, be them personal or organisation type developments. Thus a change to any of the baseline program documentation will propagate throughout your profile/organisation.

Using the Sphinx todo extension as a base, a dev.ext.todo module will be created. This can then be used to backtrack through the installation guide, creating ‘source/main/*’ files (e.g. ‘source/main/resources’), which will strip the examples out of the existing documentation, creating part files, replacing the example with a .. literalinclude:: partials/… sphinx directive.

The partials will then be combined into a single script to achieve the same result (tldr;).

Using this pattern, issue templates can then be created, containing the required fields, to create an issue of that type.

A daemon can then be written to:

• poll either a local inbox, or the remote issues repository directly

• extract the most pertinent issue

• create or checkout a feature/bugfix branch

• create a final test, as defined in the issue template

• loop a development/documentation runner until the test passes, during this

  process, as much boiler plate work as possible will be done, including

  • creating modules/packages

  • docstrings/header/meta information

  • module imports

  • default/NotSet module level constants/variables

  • class/method definitions

  • function definitions

  • initial try/catch block, with Exceptions thrown as

    exception type, exception value, stack trace

    else …

  • return values where applicable in methods/functions

---

The following base programs will be configured…

Contents

• Requirements
  • Shell/Bash
  • Python
  • Sphinx
  • SSH
  • GPG
  • Git
  • Poetry
  • Nginx
  • Indices and tables
• Configuration
  • Bash Configuration
  • Python Configuration
  • Sphinx Configuration
  • SSH Configuration
  • GPG Configuration
  • Git Configuration
  • Poetry Configuration
  • Nginx Configuration
  • Indices and tables
• Getting started
  • Creating the project
  • Git init
  • gitflow
  • pyproject
  • Directory layout
  • Create source tree
  • Add header/meta information
  • Check again

Getting start

To quickly get up and running with a development documentation server, the following are required

1. A shell (bash is used throughout)

2. python

3. sphinx

4. git

5. poetry

6. nginx

Recommended

It is highly recommended to create a dedicated user for development work, the following convention is used throughout

$USERNAME-$ENVIRONMENT

Example:

username-dev

username-test

…

username-prod

When using a dedicated user, ssh will be utilized with the ‘-Y’ option to enable GUI applications to continue to function, more later…

Making HTML documenation

The irony…

(Assuming you have this project in your home directory, although this is not where it should be ;-))

From this project root, try the following command:[cheat]

~/documentation $ make html

If you get the following:

…

Build finished. The HTML pages are in build/html.

Then skip to view-html

otherwise, if you get the the following error:

make: sphinx-build: No such file or directory
make: *** [Makefile:40: html] Error 127

then you don’t have sphinx installed, to install it, do the following:

~/documentation $ pip install sphinx --user
~/documentation $ export PATH=$HOME/.local/bin:$PATH
~/documentation $ if [[ ! `grep ".local/bin" ~/.basrhc` ]]; then
   printf "\nPATH=%s/.local/bin:\$PATH\n" $HOME >> $HOME/.bashrc
fi

This performs the following:

1. Installs sphinx into the local path

2. exports the local path to the current environment

3. Tests if this is NOT in the rc file,

   if [[ ! `grep “.local/bin” ~/.basrhc` ]]

   if this tests positive, then it’s added to the rc file to make sure the local path is always in the environment (with line breaks around the entry to avoid clobbering the last entry if there’s no end line present).

   (i.e. $HOME/.local/bin is NOT on the current path)

   printf “\nPATH=%s/.local/bin:$PATH\n” $HOME >> $HOME/.bashrc

You can see the current path with:

~/documentation $ echo $PATH
[...]/.local/bin:/usr/local/sbin:/usr/local/bin...

And now run make html again.

Congratulations, you now have sphinx installed locally!

To view the generated HTML documentation:

Sphinx has many configuration options, a few will be Sphinx configured now

~/documentation $ if [[ ! -f configure-spinx.rst ]]; then
printf ".. _conf:\n\nSphinx configuration\n====================" > \
    source/configure-sphinx.rst
fi

Then make html again to update the HTML.

This creates the document linked to in the toc configure-sphinx (source/configure-sphinx.rst), this now needs to be updated with how to configure Sphinx.

View HTML

To open the documentation in your browser:

~ $ xdg-open build/html/index.html &

This will open the index page in your default browser as a background process, leaving your shell free to make html and others…

Note

For the documentation installation, the ‘–user’ option for pip will be utilitised.

This affords the luxury of developing without worrying about package management, leaving that to poetry/ the auto module builder…

Indices and tables

• Index

• Search Page

[cheat]

Skipped creating this project, Eclipse with the Eclipse ReST plugin was used to quick start.