mkdocs: initial html documentation

changelog/0004.md

@@ -0,0 +1,3 @@
+### Added
+
+- mkdocs generated from files inside the docs directory and docstrings in the code

docs/api.md

@@ -1,5 +1,14 @@
 # API
 
+## User Dashboard module
+### serializers
+
+::: apps.userdashboard.serializers
+### views
+
+::: apps.userdashboard.views
+
+
 ## users and permissions
 We enabled token authentification in a+. So to use the APIs,
 the user token has to be given instead of name and password.

docs/index.md

@@ -0,0 +1,35 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.
+
+theme:
+  name: "material"
+
+nav:
+  - API Reference: api.md
+  - Software Architecure Reference: software_architecture.md
+  - Django Shell Reference: django_shell_basics.md.md
+  - Management Commands Reference: management_commands.md
+  - CK Editor Reference: ckeditor.md
+  - Language and Translation Reference: languages_and_translations.md
+  - Production Server Installation Reference: installation_prod.md
+  - Contribution Reference: contributing.md
+  - Project Insights Reference: project_insights.md
+  - Code Reference: reference.md
+  - Celery Reference: celery.md
+
+

docs/reference.md

@@ -0,0 +1,9 @@
+This part of the project documentation focuses on
+an **information-oriented** approach. Use it as a
+reference for the technical implementation of the
+`adhocracy+` project code.
+
+::: apps.projects.models
+::: apps.projects.views
+::: apps.projects.forms
+::: apps.projects.tasks

mkdocs.yml

@@ -0,0 +1,25 @@
+site_name: Adhocracy+
+
+nav:
+  - Home: index.md
+  - API:
+    - django basics: django_shell_basics.md 
+    - api: api.md
+    - celery: celery.md 
+    - ckeditor: ckeditor.md 
+    - management commands: management_commands.md 
+    - project insights: project_insights.md 
+    - reference: reference.md 
+    - translations: languages_and_translations.md 
+    - architecture: software_architecture.md 
+    - tests: tests.md
+  - Install: installation_prod.md
+  - Contribute: contributing.md
+
+
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+

requirements/dev.txt

@@ -6,6 +6,8 @@ Faker==18.10.1
 flake8==6.0.0
 freezegun==1.2.2
 isort==5.12.0
+mkdocs==1.6.0
+mkdocstrings==0.24.3
 psycopg[binary]==3.1.18
 pytest==7.3.2
 pytest-cov==4.1.0