DSP-UI Documentation
This is the DSP-UI library documentation, based on MkDocs and published under http://dasch-swiss.github.io/dsp-ui-lib.
Contribute
If you would like to add your own contributions to the docs, please read the following information regarding the file structure to ensure you follow the same structure.
File structure
The documentation consists of three main topics with subordinate themes:
- index contains all information about the DSP-UI
- how-to-use contains all about the usage of the DSP-UI modules
- Getting Started = All about the installation and init configuration
- Core = Documentation for the core module content
- Viewer = Documentation for the viewer module content
- Search = Documentation for the search module content
- Action = Documentation for the action module content
- how-to-contribute contains all information for people who wants to contribute to DSP-UI
- Contribution = How to contribute incl. link to the general DSP contribution guidelines (https://docs.dasch.swiss/developers/dsp/contribution/)
- Design Documentation = Structure conventions
- Docs Documentation = This document
- Release Notes = Contains the CHANGELOG file of DSP-UI
Images like screenshots and so on have to be stored in assets/images.
The mkdocs.yml file is present in the top-level directory of the repo and the source files are in the docs/ folder.
Plugins have to be defined in requirements.txt and in the github actions workflow deploy-docs step under EXTRA_PACKAGES.
Getting Started
To run the documentation locally you'll need Python installed, as well as the Python package manager pip. You can check if you already have these installed by running the following commands from the command line:
$ python --version
Python 3.8.2
$ pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
MkDocs supports Python versions 3.5, 3.6, 3.7, 3.8, and pypy3.
Installing dependencies
Install the required packages by running the following command:
make install-requirements
Running the documentation locally
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yml (repository's root folder) configuration file, and then start the server by running the following command:
$ make docs-serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes
Open up http://127.0.0.1:8000/ in your browser, and you'll see the documentation start page being.
In case you need to clean the project directory, run:
make docs-clean
To get some help about the make commands, run:
make help
Building the documentation
To build the documentation, run:
make docs-build
Deploying github page
On each release of DSP-UI, a github action script will build and deploy the documentation on dasch-swiss.github.io/dsp-ui-lib. Behind the scenes, MkDocs builds the documentation and uses the mkdocs-deploy-gh-pages actions script to deploy them to the gh-pages. That's it!