Documentation

Documentation is a key building block of good software. Software without good documentation will not be used and results in frustration for its users. Therefore, nessy aims to provide an excellent documentation. New features or refactorings, will only be merged into the framework, if they come with complete documentation.

Info

The documentation is hosted here. The staging environment is available here.

The documentation consists of

• Documentation
• Extend the mkdocs navigation
• Developer Guide
• User Guide
• Reference

CLOE Documentation

For additional information on how to write documentation, please refer to the CLOE Documentation Guide.

MkDocs

The documentation is built using MkDocs, please check the MkDocs Reference for styling and functionality options

Extend the mkdocs navigation

The documentation settings are stored in mkdocs.yml at the root of the repository. The navigation can be adjusted under the nav keyword.

The top-level keywords are rendered as "Navigation Tabs" on the Homepage. The list below those, is rendered within a sidebar.

Developer Guide

The Developer Guide should specify details, that are relevant to future developers of nessy. It must state details of the implementation, that are relevant to understand it for refactorings or extensions.

Trying to remember why you created a class or function in a certain way 5 months ago is a tedious task. Now try to understand someone elses code - this might quickly become frustrating! And that's why we write this Developer Guide!

User Guide

The User Guide is meant to enable users of nessy. It should provide:

1. How To's : How-to guides take the reader through the steps required to solve a real-world problem.
2. Tutorials : Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it.

The structure of the User Guide is:

.
├── how-to
│   └── how_to_use_submodule_1.md
│   └── ...
├── installation.md
└── tutorials
    └── create-a-simple-etl-pipeline.md
    └── ...

Reference

The reference is automatically populated by the docstrings. The docstrings are expected to be written in in google style.

The docstrings are parsed using mkdocstrings, please refer to their documentation to get the full overview of their features. Some highlights are the referral to classes or functions in a simple path.to.class syntax and the show_inheritance_diagram option, which shows a Class Diagram for inherited classes.

All public classes and functions, i.e. those, that don't start with _, must provide a docstring.