Update Sphinx and documentation (#3710)

Co-authored-by: Jeroen Dekkers <[email protected]> Co-authored-by: Jan Klopper <[email protected]>
minvws · Oct 24, 2024 · 39b92e7 · 39b92e7
1 parent 5f4bfe1
commit 39b92e7
Show file tree

Hide file tree

Showing 96 changed files with 535 additions and 1,778 deletions.
diff --git a/.github/workflows/build_docs_on_pr.yml b/.github/workflows/build_docs_on_pr.yml
@@ -3,7 +3,14 @@ name: Build docs artifact for PR
 on:
   pull_request:
     paths:
+      # We generate documentation for boefje, bytes, keiko, mula and octopoes
+      # from code so the workflow should also depend on it.
+      - "boefje/**"
+      - "bytes/**"
       - "docs/**"
+      - "keiko/**"
+      - "mula/**"
+      - "octopoes/**"
       - "requirements.txt"
       - ".github/workflows/build_docs_on_pr.yml"
 

diff --git a/.gitignore b/.gitignore
@@ -437,7 +437,14 @@ nl-kat-*
 /_version.py
 
 # Automatically generated markdown files for the environment variables
-/docs/source/technical_design/environment_settings/*.md
+docs/source/installation-and-deployment/environment-settings/boefjes.md
+docs/source/installation-and-deployment/environment-settings/bytes.md
+docs/source/installation-and-deployment/environment-settings/keiko.md
+docs/source/installation-and-deployment/environment-settings/mula.md
+docs/source/installation-and-deployment/environment-settings/octopoes.md
+
+docs/source/_static/d3.min.js
+docs/source/_static/mermaid.min.js
 
 # rpki cache
 /boefjes/boefjes/plugins/kat_rpki/rpki.json

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -188,5 +188,6 @@ repos:
           \.json$ |
           \.min\.js$ |
           ^rocky/assets/css/themes/soft/fonts |
-          ^rocky/assets/vendors
+          ^rocky/assets/vendors |
+          ^docs/source/_static
           )
diff --git a/Makefile b/Makefile
@@ -12,12 +12,14 @@ UNAME := $(shell uname)
 export DOCKER_BUILDKIT=1
 export COMPOSE_DOCKER_CLI_BUILD=1
 
+# We can't really return an error here, so if settings-doc fails we delete the
+# file which will result in sphinx-build returning an error later on
 define build-settings-doc
-	echo "# $(4)" > docs/source/installation_and_deployment/environment_settings/$(3).md
+	echo "# $(4)" > docs/source/installation-and-deployment/environment-settings/$(3).md
 	DOCS=True PYTHONPATH=./$(1) settings-doc generate \
 	-f markdown -m $(2) \
 	--templates docs/settings-doc-templates \
-	>> docs/source/installation_and_deployment/environment_settings/$(3).md
+	>> docs/source/installation-and-deployment/environment-settings/$(3).md || exit 1
 endef
 
 
@@ -114,7 +116,12 @@ docs:
 	$(call build-settings-doc,bytes,bytes.config,bytes,Bytes)
 	$(call build-settings-doc,mula/scheduler,config.settings,mula,Mula)
 
-	PYTHONPATH=$(PYTHONPATH):boefjes/:bytes/:keiko/:mula/:octopoes/ sphinx-build -b html docs/source docs/_build
+	curl -sL -o - https://registry.npmjs.org/d3/-/d3-7.9.0.tgz | tar -Oxzf - package/dist/d3.min.js > docs/source/_static/d3.min.js
+	curl -sL -o - https://registry.npmjs.org/mermaid/-/mermaid-11.3.0.tgz | tar -Oxzf - package/dist/mermaid.min.js > docs/source/_static/mermaid.min.js
+	echo "f2094bbf6141b359722c4fe454eb6c4b0f0e42cc10cc7af921fc158fceb86539  docs/source/_static/d3.min.js" | sha256sum --quiet --check || exit 1
+	echo "0d2b6f2361e7e0ce466a6ed458e03daa5584b42ef6926c3beb62eb64670ca261  docs/source/_static/mermaid.min.js" | sha256sum --quiet --check || exit 1
+
+	PYTHONPATH=$(PYTHONPATH):boefjes/:bytes/:keiko/:mula/:octopoes/ sphinx-build -b html --fail-on-warning docs/source docs/_build
 
 
 poetry-dependencies:

diff --git a/docs/source/_static/mermaid-9.4.3.min.js b/docs/source/_static/mermaid-9.4.3.min.js
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -59,5 +59,13 @@
 html_static_path = ["_static"]
 html_css_files = ["openkat.css"]
 
-mermaid_version = ""  # Do not fetch from the CDN
-html_js_files = ["mermaid-9.4.3.min.js"]
+mermaid_use_local = "mermaid.min.js"
+mermaid_include_elk = ""
+d3_use_local = "d3.min.js"
+
+autosectionlabel_prefix_document = True
+
+suppress_warnings = [
+    f"autosectionlabel.installation-and-deployment/environment-settings/{document}"
+    for document in ("boefjes", "bytes", "keiko", "mula", "octopoes")
+]
diff --git a/...developer_documentation/boefjes-runner.md → ...developer-documentation/boefjes-runner.md b/...developer_documentation/boefjes-runner.md → ...developer-documentation/boefjes-runner.md
@@ -265,7 +265,7 @@ having been implemented in these PRs:
 - https://github.com/minvws/nl-kat-coordination/pull/2709
 - https://github.com/minvws/nl-kat-coordination/pull/2832
 
-#### Summary of decisions
+### Summary of decisions
 
 We decided not to focus on the following:
 

diff --git a/...source/developer_documentation/boefjes.md → ...source/developer-documentation/boefjes.md b/...source/developer_documentation/boefjes.md → ...source/developer-documentation/boefjes.md
@@ -3,7 +3,7 @@
 This module has several entry points discussed below, but let us first consider the prerequisites and scope.
 If you already have a running setup and want to learn where each bit of functionality goes, read the following page:
 
-[Developing Openkat Plugins](../introduction/makeyourown.rst)
+[Developing Openkat Plugins](../introduction/make-your-own.rst)
 
 ## Prerequisites
 

diff --git a/docs/source/developer_documentation/bytes.md → docs/source/developer-documentation/bytes.md b/docs/source/developer_documentation/bytes.md → docs/source/developer-documentation/bytes.md
diff --git a/...on/development_tutorial/creating_a_bit.md → ...tion/development-tutorial/creating-bit.md b/...on/development_tutorial/creating_a_bit.md → ...tion/development-tutorial/creating-bit.md
diff --git a/...development_tutorial/creating_a_boefje.md → ...n/development-tutorial/creating-boefje.md b/...development_tutorial/creating_a_boefje.md → ...n/development-tutorial/creating-boefje.md
diff --git a/...elopment_tutorial/creating_a_new_model.md → ...on/development-tutorial/creating-model.md b/...elopment_tutorial/creating_a_new_model.md → ...on/development-tutorial/creating-model.md
diff --git a/...lopment_tutorial/creating_a_normalizer.md → ...velopment-tutorial/creating-normalizer.md b/...lopment_tutorial/creating_a_normalizer.md → ...velopment-tutorial/creating-normalizer.md
diff --git a/...development_tutorial/creating_a_report.md → ...n/development-tutorial/creating-report.md b/...development_tutorial/creating_a_report.md → ...n/development-tutorial/creating-report.md
@@ -77,7 +77,7 @@ After having done all that. The user should be able to create their own Greeting
 
 Let's go to the reports tab, and change our filters again so we can see our Greetings OOI. Check one of their boxes and press the _Continue with selection_ button. Now in the grid of available report types you can make, you should see 2 options. The Findings Report and the Greetings Report. Let's check them both and press once more on the _Continue with selection_ button. Now you will see a report that includes both the Findings Report and the Greetings report inside a single web page. In the top right, you can press the _Export_ button which will make a pdf of your report. Including information about every finding of your project.
 
-If you want to get more information inside your report, make sure to check our [technical report documentation](https://docs.openkat.nl/developer_documentation/rocky.html#testing) about reports.
+If you want to get more information inside your report, make sure to check our documentation about {ref}`developer-documentation/reports:Creating reports`.
 
 ## Conclusion
 

diff --git a/...umentation/development_tutorial/index.rst → ...umentation/development-tutorial/index.rst b/...umentation/development_tutorial/index.rst → ...umentation/development-tutorial/index.rst
@@ -24,9 +24,9 @@ Glossary
    :caption: Contents
    :maxdepth: 1
 
-   creating_a_boefje
-   testing_the_boefje
-   creating_a_new_model
-   creating_a_normalizer
-   creating_a_bit
-   creating_a_report
+   creating-boefje
+   testing-boefje
+   creating-model
+   creating-normalizer
+   creating-bit
+   creating-report
diff --git a/...evelopment_tutorial/testing_the_boefje.md → ...on/development-tutorial/testing-boefje.md b/...evelopment_tutorial/testing_the_boefje.md → ...on/development-tutorial/testing-boefje.md
diff --git a/...loper_documentation/img/boefje_design.png → ...loper-documentation/img/boefje_design.png b/...loper_documentation/img/boefje_design.png → ...loper-documentation/img/boefje_design.png
diff --git a/...er_documentation/img/kat_data_example.png → ...er-documentation/img/kat_data_example.png b/...er_documentation/img/kat_data_example.png → ...er-documentation/img/kat_data_example.png
diff --git a/..._documentation/img/kat_data_structure.png → ...-documentation/img/kat_data_structure.png b/..._documentation/img/kat_data_structure.png → ...-documentation/img/kat_data_structure.png
diff --git a/...oper_documentation/img/kat_query_plan.png → ...oper-documentation/img/kat_query_plan.png b/...oper_documentation/img/kat_query_plan.png → ...oper-documentation/img/kat_query_plan.png
diff --git a/...per_documentation/img/kat_ref_example.png → ...per-documentation/img/kat_ref_example.png b/...per_documentation/img/kat_ref_example.png → ...per-documentation/img/kat_ref_example.png
diff --git a/...n/img/octopoes/authoritative_database.png → ...n/img/octopoes/authoritative_database.png b/...n/img/octopoes/authoritative_database.png → ...n/img/octopoes/authoritative_database.png
diff --git a/...documentation/img/octopoes/claimspace.png → ...documentation/img/octopoes/claimspace.png b/...documentation/img/octopoes/claimspace.png → ...documentation/img/octopoes/claimspace.png
diff --git a/...tion/img/octopoes/claimspace_dataflow.png → ...tion/img/octopoes/claimspace_dataflow.png b/...tion/img/octopoes/claimspace_dataflow.png → ...tion/img/octopoes/claimspace_dataflow.png
diff --git a/...r_documentation/img/octopoes/dataflow.png → ...r-documentation/img/octopoes/dataflow.png b/...r_documentation/img/octopoes/dataflow.png → ...r-documentation/img/octopoes/dataflow.png
diff --git a/...documentation/img/octopoes/event_loop.png → ...documentation/img/octopoes/event_loop.png b/...documentation/img/octopoes/event_loop.png → ...documentation/img/octopoes/event_loop.png
diff --git a/..._documentation/img/octopoes/factspace.png → ...-documentation/img/octopoes/factspace.png b/..._documentation/img/octopoes/factspace.png → ...-documentation/img/octopoes/factspace.png
diff --git a/...tion/img/octopoes/graph_rule_patterns.png → ...tion/img/octopoes/graph_rule_patterns.png b/...tion/img/octopoes/graph_rule_patterns.png → ...tion/img/octopoes/graph_rule_patterns.png
diff --git a/...ctopoes/inference_and_materialization.png → ...ctopoes/inference_and_materialization.png b/...ctopoes/inference_and_materialization.png → ...ctopoes/inference_and_materialization.png
diff --git a/...ation/img/octopoes/inference_chaining.png → ...ation/img/octopoes/inference_chaining.png b/...ation/img/octopoes/inference_chaining.png → ...ation/img/octopoes/inference_chaining.png
diff --git a/.../octopoes/knowledge_derived_knowledge.png → .../octopoes/knowledge_derived_knowledge.png b/.../octopoes/knowledge_derived_knowledge.png → .../octopoes/knowledge_derived_knowledge.png
diff --git a/...tion/img/octopoes/logic_and_reasoning.png → ...tion/img/octopoes/logic_and_reasoning.png b/...tion/img/octopoes/logic_and_reasoning.png → ...tion/img/octopoes/logic_and_reasoning.png
diff --git a/...cumentation/img/octopoes/owa_database.png → ...cumentation/img/octopoes/owa_database.png b/...cumentation/img/octopoes/owa_database.png → ...cumentation/img/octopoes/owa_database.png
diff --git a/.../source/developer_documentation/index.rst → .../source/developer-documentation/index.rst b/.../source/developer_documentation/index.rst → .../source/developer-documentation/index.rst
@@ -14,8 +14,8 @@ Contains documentation for developers and contributors.
    normalisers-runner
    bytes
    octopoes
-   octopoes_models
-   octopoes_research
+   octopoes-models
+   octopoes-research
    keiko
    reports
-   development_tutorial/index
+   development-tutorial/index
diff --git a/docs/source/developer_documentation/keiko.md → docs/source/developer-documentation/keiko.md b/docs/source/developer_documentation/keiko.md → docs/source/developer-documentation/keiko.md
@@ -49,7 +49,7 @@ template is started. After the report is generated, the PDF is available at `/re
 ## Logging
 
 Keiko logging can be configured through by supplying a `logging.json`, relative to the current working directory of the
-process. See [logging.json](logging.json) for an example.
+process. See `keiko/logging.json` for an example.
 
 ## Building a new template
 

diff --git a/docs/source/developer_documentation/mula.md → docs/source/developer-documentation/mula.md b/docs/source/developer_documentation/mula.md → docs/source/developer-documentation/mula.md
diff --git a/...loper_documentation/normalisers-runner.md → ...loper-documentation/normalisers-runner.md b/...loper_documentation/normalisers-runner.md → ...loper-documentation/normalisers-runner.md
@@ -6,7 +6,7 @@ _Status: Draft_
 
 The current workflow is as follows:
 
-```mermaid
+```{mermaid}
 graph LR;
     Mula--Tasks-->Boefjes;
     Boefjes--Information-->Bytes;

diff --git a/...veloper_documentation/octopoes_models.rst → ...veloper-documentation/octopoes-models.rst b/...veloper_documentation/octopoes_models.rst → ...veloper-documentation/octopoes-models.rst
diff --git a/...loper_documentation/octopoes_research.rst → ...loper-documentation/octopoes-research.rst b/...loper_documentation/octopoes_research.rst → ...loper-documentation/octopoes-research.rst
diff --git a/...ource/developer_documentation/octopoes.md → ...ource/developer-documentation/octopoes.md b/...ource/developer_documentation/octopoes.md → ...ource/developer-documentation/octopoes.md
@@ -413,7 +413,7 @@ python3 octopoes/tools/xtdb-cli.py -n "aa" history --with-docs "BIT_METRIC" |jq
 
 If you want to query the XTDB database directly, you can use the XTDB-tool. This is explained on the following page: https://docs.openkat.nl/developer_documentation/octopoes.html#xtdb-cli-tool.
 
-## OOI
+## OOI Objects
 
 OOI objects are instances of relatively simple classes, which inherit from `OOI`.
 

diff --git a/...tic Web Technologies in OpenKAT paper.pdf → ...tic Web Technologies in OpenKAT paper.pdf b/...tic Web Technologies in OpenKAT paper.pdf → ...tic Web Technologies in OpenKAT paper.pdf
diff --git a/...ic Web Technologies in OpenKAT slides.pdf → ...ic Web Technologies in OpenKAT slides.pdf b/...ic Web Technologies in OpenKAT slides.pdf → ...ic Web Technologies in OpenKAT slides.pdf
diff --git a/...source/developer_documentation/reports.md → ...source/developer-documentation/reports.md b/...source/developer_documentation/reports.md → ...source/developer-documentation/reports.md
@@ -31,7 +31,7 @@ class YourNameReport(Report):
 ```
 
 5. Open `reports/report_types/helpers.py` and add your new class to the `REPORTS` constant list.
-6. Implement a method within `report.py` to gather the required data for report generation. See the [Collecting data](#collecting-data) section for more information.
+6. Implement a method within `report.py` to gather the required data for report generation. See the {ref}`developer-documentation/reports:Collecting data` section for more information.
 7. Design the HTML structure for your report within `report.html`. The generated data from `report.py` can be used with Django Template in this file. For example by referring to the returned value like `{{ data }}`.
 8. Save your changes and refresh the page to see the changes you made immediately.
 
@@ -43,7 +43,7 @@ The `generate_data` method only works on single OOIs and should not be used in n
 Use all existing reports as examples to gather data for your report.
 
 - In the file `rocky/reports/report_types/definitions.py` you can find some methods that may be useful.
-- For querying data from Octopoes, consult `octopoes/octopoes/connector/octopoes.py` which contains various useful methods. Additional information on how to write queries can be found [here](https://docs.openkat.nl/developer_documentation/octopoes.html#querying).
+- For querying data from Octopoes, consult `octopoes/octopoes/connector/octopoes.py` which contains various useful methods. Additional information on how to write queries can be found {ref}`here <developer-documentation/octopoes:Querying>`.
 
 ## Writing report unit tests
 
@@ -91,4 +91,4 @@ def test_my_new_report_multiple_results(mock_octopoes_api_connector, valid_time,
 
 ### Executing unit tests
 
-Information about how to execute unit tests can be found [here](https://docs.openkat.nl/developer_documentation/rocky.html#testing).
+Information about how to execute unit tests can be found {ref}`here <rocky-testing>`.
diff --git a/docs/source/developer_documentation/rocky.md → docs/source/developer-documentation/rocky.md b/docs/source/developer_documentation/rocky.md → docs/source/developer-documentation/rocky.md
@@ -98,6 +98,8 @@ $ make build-rocky-frontend
 
 ## Development
 
+(rocky-testing)=
+
 ### Testing
 
 To run all unit tests, run:

diff --git a/docs/source/guidelines/contributions.rst b/docs/source/guidelines/contributions.rst
@@ -18,15 +18,15 @@ Contribute to Codebase
 ======================
 
 
-See :ref:`Development` for our code style, coding conventions, and overall workflow.
+See :doc:`/guidelines/development` for our code style, coding conventions, and overall workflow.
 
 - Fork the right repository in GitHub
 - Create a new branch from either ``main`` or a release tag. Note that ``main`` changes rapidly, and as such may not be a suitable basis for your work.
     - This branch should be in the following format:
     - ``[feature|enhancement|bug|hotfix]/random-cat-popup-on-screen``
 - Commit and push the code
-    - Make sure the code is linted, formatted and has correct typing. Use ``pre-commit`` locally for this, see :ref:`Pre-commit`.
-    - All commits must be signed, see :ref:`Signed commits`.
+    - Make sure the code is linted, formatted and has correct typing. Use ``pre-commit`` locally for this, see :ref:`guidelines/development:Pre-commit`.
+    - All commits must be signed, see :ref:`guidelines/development:Signed commits`.
 - Submit Pull Request
     - Make sure your code is tested and the PR has a good title and description
     - Use the PR template
@@ -98,7 +98,7 @@ The new language should be automatically picked up by both Weblate and Django.
 
 Contributor Social Contract
 ===========================
-All contributors (including, but not limited to, developers and issue reporters) promise to do their best to adhere to the guidelines in :ref:`Project Guidelines`.
+All contributors (including, but not limited to, developers and issue reporters) promise to do their best to adhere to the guidelines in :doc:`/guidelines/index`.
 Everyone is encouraged to politely and constructively point out guidelines violations to others.
 Actively enforcing these guidelines makes that the entire project benefits in quality control.
 

diff --git a/docs/source/guidelines/development.rst b/docs/source/guidelines/development.rst
@@ -13,7 +13,7 @@ Developers are encouraged to write their code as strictly compliant as possible.
 Tools
 =====
 
-To make development and validation easier, we adopted :ref:`pre-commit` hooks to automate most of this.
+To make development and validation easier, we adopted :ref:`guidelines/development:pre-commit` hooks to automate most of this.
 This will help identify broken/bad code, improve consistency and save time during code reviews.
 Some tools and hooks have been adopted for both local development as well as in our CI/CD pipeline as GitHub actions.
 
@@ -113,7 +113,7 @@ It has a simple syntax and many plugins available that should improve our test c
 Development Environment
 =======================
 
-See :ref:`Installation and deployment` for the overall installation instructions.
+See :doc:`/installation-and-deployment/index` for the overall installation instructions.
 In a development context, we strongly recommend to use the Docker setup to test and make changes in the codebase (and not production packages).
 
 When it comes to development there is no specific IDE that must be used, although many of us would choose PyCharm as the preferred IDE.

diff --git a/docs/source/guidelines/management.rst b/docs/source/guidelines/management.rst
@@ -26,15 +26,15 @@ When a cycle has been completed, we hold a quick retrospective to evaluate what
 Bugs and Feature Requests
 =========================
 
-For effective bug reporting and feature requests there are :ref:`GitHub Templates`.
+For effective bug reporting and feature requests there are :doc:`/templates/index`.
 These should be used and submitted in the coordination repository's `issues board <https://github.com/minvws/nl-kat-coordination/issues>`_.
 Please make sure to link them to the central project board as an incoming feature/refinement.
 
 
 Pull Requests
 =============
 
-Each unit of work shall be submitted as a pull request using a :ref:`Pull Request Template` and reviewed by at least one developer.
+Each unit of work shall be submitted as a pull request using a :doc:`/templates/pull_request_template_author` and reviewed by at least one developer.
 The checklist should be completed by a functional and a code reviewer.
 
 In-depth content discussions

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -10,9 +10,9 @@ Welcome to the OpenKAT documentation!
    introduction/index
    manual/index
    modules/index
-   installation_and_deployment/index
-   developer_documentation/index
-   ux_design/index
-   release_notes/index
+   installation-and-deployment/index
+   developer-documentation/index
+   ux-design/index
+   release-notes/index
    guidelines/index
    templates/index
diff --git a/...installation_and_deployment/containers.md → ...installation-and-deployment/containers.md b/...installation_and_deployment/containers.md → ...installation-and-deployment/containers.md
diff --git a/...ce/installation_and_deployment/cveapi.rst → ...ce/installation-and-deployment/cveapi.rst b/...ce/installation_and_deployment/cveapi.rst → ...ce/installation-and-deployment/cveapi.rst
diff --git a/...allation_and_deployment/debianinstall.rst → ...llation-and-deployment/debian-install.rst b/...allation_and_deployment/debianinstall.rst → ...llation-and-deployment/debian-install.rst
@@ -6,7 +6,7 @@ OpenKAT has Debian packages available. In the near future we will have an apt
 repository that will allow you to keep your installation up-to-date using apt.
 An installation of KAT can be done on a single machine or spread out on several
 machines for a high availability setup. This guide will take you through the
-steps for installing it on a single machine. There are also :ref:`scripts<Scripts>`
+steps for installing it on a single machine. There are also :doc:`/installation-and-deployment/scripts`
 available if you don't want to do this by hand.
 
 Supported distributions

diff --git a/...d_deployment/debuggingtroubleshooting.rst → ...-deployment/debugging-troubleshooting.rst b/...d_deployment/debuggingtroubleshooting.rst → ...-deployment/debugging-troubleshooting.rst
@@ -80,4 +80,4 @@ Check in the user interface if the users have permission to perform scans and ar
 
 The current usermodel also needs a superuser that is part of an organization. Normally this is set automagically. With several organizations in your instance the superuser might end up alone. This must be corrected through the Django interface, in which the superuser can be added to the organization.
 
-You can reach the Django admin interface through ``/admin`` on the rocky instance. While you are there, do check the :ref:`Production: Hardening OpenKAT` page if you have not already done so.
+You can reach the Django admin interface through ``/admin`` on the rocky instance. While you are there, do check the :doc:`/installation-and-deployment/hardening` page if you have not already done so.
diff --git a/...deployment/environment_settings/index.rst → ...deployment/environment-settings/index.rst b/...deployment/environment_settings/index.rst → ...deployment/environment-settings/index.rst
diff --git a/..._deployment/environment_settings/rocky.md → ...-deployment/environment-settings/rocky.md b/..._deployment/environment_settings/rocky.md → ...-deployment/environment-settings/rocky.md
diff --git a/...and_deployment/externalauthentication.rst → ...nd-deployment/external-authentication.rst b/...and_deployment/externalauthentication.rst → ...nd-deployment/external-authentication.rst
diff --git a/...ce/installation_and_deployment/gitpod.rst → ...ce/installation-and-deployment/gitpod.rst b/...ce/installation_and_deployment/gitpod.rst → ...ce/installation-and-deployment/gitpod.rst
diff --git a/...installation_and_deployment/hardening.rst → ...installation-and-deployment/hardening.rst b/...installation_and_deployment/hardening.rst → ...installation-and-deployment/hardening.rst
diff --git a/...tallation_and_deployment/img/dockerps.png → ...tallation-and-deployment/img/dockerps.png b/...tallation_and_deployment/img/dockerps.png → ...tallation-and-deployment/img/dockerps.png
diff --git a/...llation_and_deployment/img/healthpage.png → ...llation-and-deployment/img/healthpage.png b/...llation_and_deployment/img/healthpage.png → ...llation-and-deployment/img/healthpage.png
diff --git a/...ation_and_deployment/img/infraopenkat.png → ...ation-and-deployment/img/infraopenkat.png b/...ation_and_deployment/img/infraopenkat.png → ...ation-and-deployment/img/infraopenkat.png
diff --git a/...rce/installation_and_deployment/index.rst → ...rce/installation-and-deployment/index.rst b/...rce/installation_and_deployment/index.rst → ...rce/installation-and-deployment/index.rst
@@ -1,4 +1,4 @@
-Installation and deployment
+Installation and Deployment
 ###########################
 
 Contains documentation for developers and contributors.
@@ -9,15 +9,15 @@ Contains documentation for developers and contributors.
 
    install
    containers
-   debianinstall
+   debian-install
    scripts
    hardening
-   localinstall
-   windowsinstall
+   local-install
+   windows-install
    gitpod
    nginx
-   debuggingtroubleshooting
+   debugging-troubleshooting
    latex
-   environment_settings/index
-   externalauthentication
+   environment-settings/index
+   external-authentication
    cveapi
diff --git a/...e/installation_and_deployment/install.rst → ...e/installation-and-deployment/install.rst b/...e/installation_and_deployment/install.rst → ...e/installation-and-deployment/install.rst
diff --git a/...rce/installation_and_deployment/latex.rst → ...rce/installation-and-deployment/latex.rst b/...rce/installation_and_deployment/latex.rst → ...rce/installation-and-deployment/latex.rst
diff --git a/...tallation_and_deployment/localinstall.rst → ...allation-and-deployment/local-install.rst b/...tallation_and_deployment/localinstall.rst → ...allation-and-deployment/local-install.rst
diff --git a/...rce/installation_and_deployment/nginx.rst → ...rce/installation-and-deployment/nginx.rst b/...rce/installation_and_deployment/nginx.rst → ...rce/installation-and-deployment/nginx.rst
diff --git a/...e/installation_and_deployment/scripts.rst → ...e/installation-and-deployment/scripts.rst b/...e/installation_and_deployment/scripts.rst → ...e/installation-and-deployment/scripts.rst
@@ -4,7 +4,7 @@ Scripts
 There are some scripts in the `scripts/installation
 <https://github.com/minvws/nl-kat-coordination/tree/main/scripts/installation>`__ directory
 that can be used to install and update OpenKAT on Debian and will do all the
-steps described on the :ref:`Debian installation<Production: Debian packages>` page.
+steps described on the :doc:`/installation-and-deployment/debian-install` page.
 
 Installation
 ------------

diff --git a/...llation_and_deployment/windowsinstall.rst → ...lation-and-deployment/windows-install.rst b/...llation_and_deployment/windowsinstall.rst → ...lation-and-deployment/windows-install.rst
@@ -106,4 +106,4 @@ Now you can start OpenKat.
 Troubleshooting
 ================
 
-If you encounter any problems, please check `OpenKAT Troubleshooting <https://docs.openkat.nl/installation_and_deployment/index.html>`_.
+If you encounter any problems, please check :doc:`/installation-and-deployment/index` for more information.
diff --git a/docs/source/introduction/howdoesitwork.rst → .../source/introduction/how-does-it-work.rst b/docs/source/introduction/howdoesitwork.rst → .../source/introduction/how-does-it-work.rst
diff --git a/docs/source/introduction/index.rst b/docs/source/introduction/index.rst
@@ -8,5 +8,5 @@ Contains introduction into OpenKAT
    :caption: Contents
 
    intro
-   howdoesitwork
-   makeyourown
+   how-does-it-work
+   make-your-own
diff --git a/docs/source/introduction/intro.rst b/docs/source/introduction/intro.rst
@@ -37,14 +37,14 @@ The nicest playground for OpenKAT is a situation where many systems are active.
 Where do I start with OpenKAT?
 ==============================
 
-The documentation explains how the system works and what the main principles are. This gives an impression, but after reading the documentation, trying it yourself is the best way to find out how OpenKAT works. There are `several options to install OpenKAT <https://docs.openkat.nl/installation_and_deployment/index.html>`_.
+The documentation explains how the system works and what the main principles are. This gives an impression, but after reading the documentation, trying it yourself is the best way to find out how OpenKAT works. There are :doc:`/installation-and-deployment/index`
 
-The easiest way to get to know the system is a local installation. If you don't have a debian or ubuntu machine (yet), try the Gitpod test environment. `The installation chapter <https://docs.openkat.nl/installation_and_deployment/index.html>`_ has a comprehensive roadmap for creating a local installation. In addition to the documentation, read `the readme from the general repository <https://github.com/minvws/nl-kat-coordination>`_.
+The easiest way to get to know the system is a local installation. If you don't have a debian or ubuntu machine (yet), try the Gitpod test environment. :doc:`/installation-and-deployment/install` has a comprehensive roadmap for creating a local installation. In addition to the documentation, read `the readme from the general repository <https://github.com/minvws/nl-kat-coordination>`_.
 
 Where is the software located?
 ==============================
 
-OpenKAT consists of separate modules that each perform a specific task. All modules are located in the `NL-KAT-Coordination <https://github.com/minvws/nl-kat-coordination>`_ repository. The :ref:`Modules of OpenKAT<modules>` section of the documentation goes into detail on each of these modules.
+OpenKAT consists of separate modules that each perform a specific task. All modules are located in the `NL-KAT-Coordination <https://github.com/minvws/nl-kat-coordination>`_ repository. The :doc:`/modules/modules` section of the documentation goes into detail on each of these modules.
 
 Responsible disclosure
 ======================

diff --git a/docs/source/introduction/makeyourown.rst → docs/source/introduction/make-your-own.rst b/docs/source/introduction/makeyourown.rst → docs/source/introduction/make-your-own.rst
diff --git a/docs/source/introduction/img/report.png → docs/source/manual/img/report.png b/docs/source/introduction/img/report.png → docs/source/manual/img/report.png
diff --git a/docs/source/manual/index.rst b/docs/source/manual/index.rst
@@ -7,6 +7,6 @@ An overview of all KAT functionality, from a user perspective.
    :maxdepth: 4
    :caption: Contents
 
-   usermanual
+   user-manual
    reports
    normalizers