How to write and build the documentation

Requirements

If you are not interested in compiling the documentation, you may skip this part.

The automatic code documentation uses TypeDoc. The correct dependency for this is already placed inside the package.json inside the bsrap-app directory, so all that is left for you to do is to install all dependencies using npm install. You may as well check the version of typedoc in that file and install it yourself.

The manually written documentation uses Sphinx, which introduces a whole bunch of other dependencies as well. The most important one being Python, you can install all others with pip. All dependencies were captures inside the requirements.txt, located inside the docs folder. All you need to do is to install Python and then run

pip install -r requirements.txt

Building both manual and automatic documentation

If you wish to build the documentation as a whole, run

npm run docs

from within the bsrap-app directory.

Note

You will need to install all of the above mentioned dependencies first.

Manual documentation

Structure

The hand-written documentation is compiled from text files in /docs/source/ into HTML using Sphinx. The static HTML files will be located in /docs/build/ You may use either Markdown (.md) or the natively supported ReStructured Text (.rst) for your source files.

The documentation itself is separated into top-level categories, which can be found inside docs/source/files/categories. Those will be displayed on the initial site of the documentation. The content of each category is placed inside a folder which has the same name as the category. Those folders are located in /docs/source/files/. You may also create subpages and subfolders within those directories.

Building

To compile the documentation, execute make html from within the docs folder at the top of the repository.

Automatic documentation

Structure

Code which is located at bsrap-app/src/lib is detected using TypeDoc and the code documentation is automatically compiled into static (standalone) HTML sites. The configuration for typedoc can be found inside bsrap-app/typedoc.json.

Building

The build process can be invoked using the

npx typedoc

command.