Contributing to Liminal docs

Apache Liminal use Sphinx and readthedocs.org to create and publish documentation to readthedocs.org

Basic setup

Here is what you need to do in order to work and create docs locally

Installing sphinx and documentation

More details about sphinx and readthedocs can be found here:

Here is what you need to do:

pip install sphinx

Inside your project go to docs lib, update the docs you like and build them:

cd docs
make html

Automatically rebuild sphinx docs

pip install sphinx-autobuild
cd docs
sphinx-autobuild source/ build/html/

Now open a browser on http://localhost:8000/ Your docs will automatically update

Rebuilding the pythondoc liminal code documentation

cd docs
sphinx-apidoc -o source/ ../liminal

RunningTests

When doing local development and running Liminal unit-tests, make sure to set LIMINAL_STAND_ALONE_MODE=True

  1. Setup Minikube 2.Install python requirements: pip install -r requirements.txt
  2. Run tests: ./run_tests.sh

InstallRunPreCommit

pre-commit is used to install Python code linting and formatting tools:

Getting started

Requires python >=3.6, pre-commit>=1.14 and a git repository

  1. Run pip install pre-commit or pip install -r requirements.txt
  2. Install the hooks: Simple install without post hooks: pre-commit install

OR Install the hooks: pre-commit install --install-hooks

Optional: Install the post commit hooks: pre-commit install --hook-type post-commit

  1. To run pre commit hooks:

    1. Either run git commit the new configuration files

    2. Run pre-commit run -a to lint and format your entire project

Now on every commit, pre-commit will use a git hook to run the tools. Warning: the first commit will take some time because the tools are being installed by pre-commit

pre-commit run -a to lint and format your entire project

Resolving failed commits

  • If black fail, they have reformatted your code.
  • You should check the changes made. Then simply “git add --update .” and re-commit or git add and git commit the changes.

Example:

Fixing black failed commits

EnabledHooks

  1. black: a Python automatic code formatter
  2. yamllint: A linter for YAML files. yamllint does not only check for syntax validity, but for weirdnesses like key repetition and cosmetic problems such as lines length, trailing spaces, indentation, etc.
  3. OutOfBoxHooks - Out-of-the-box hooks for pre-commit like Check for files that contain merge conflict strings
  4. Bandit is a tool designed to find common security issues in Python code.
  5. blacken-docs Run black on python code blocks in documentation files
  6. pyupgrade A tool (and pre-commit hook) to automatically upgrade syntax for newer versions of the language.
  7. isort A Python utility / library to sort imports.