diff --git a/docs/Makefile b/docs/Makefile index ec37e687c..d23be395b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,25 +1,16 @@ -# Makefile for Sphinx documentation +# Makefile for MkDocs documentation # # You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build +MKDOCS = mkdocs +BUILDDIR = site -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +# User-friendly check for mkdocs +ifeq ($(shell which $(MKDOCS) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(MKDOCS)' command was not found. Make sure you have MkDocs installed with 'pip install mkdocs mkdocs-material', then make sure the mkdocs executable is in your PATH.) endif -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: help clean html serve build help: @echo "Please use \`make ' where is one of" diff --git a/docs/README.md b/docs/README.md index 8ae7f650a..301ccfb6a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,20 +10,26 @@ Compilation into HTML To compile this documentation : -1. Install [sphinx-doc](http://sphinx-doc.org) +1. Install [MkDocs](https://www.mkdocs.org/) and MkDocs Material ``` bash $ virtualenv .venv # creation of the virtual env (only the first time) $ source .venv/bin/activate # activate the virtual env (.venv) $ pip install -r requirements.txt ``` 2. Install submodules : $ git submodule update --init; -3. run `make html` from the root directory -4. The base file is located on build/html/index.html +3. run `make html` or `mkdocs build` from the root directory +4. The base file is located on site/index.html ``` bash - $ cd build/html + $ cd site $ python -m http.server 8888 # will serve the site on the port 8888 ``` +Alternatively, you can use the built-in development server: +``` bash +(.venv) $ mkdocs serve +``` +This will start a development server at http://127.0.0.1:8000/ with live reload. + Contribute =========== diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 000000000..c1faac741 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,137 @@ +site_name: Chill Documentation +site_description: Documentation for Chill - A free software for social workers +site_url: https://docs.chill.social +repo_url: https://gitlab.com/Chill-project/chill-bundles +repo_name: Chill-project/chill-bundles + +docs_dir: source + +copyright: Copyright © 2014-2024 Champs-Libres Cooperative SCRLFS - GNU Free Documentation License v1.3 + +theme: + name: material + language: en + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.expand + - navigation.path + - navigation.top + - search.highlight + - search.share + - search.suggest + - toc.follow + - content.code.copy + - content.code.annotate + + palette: + # Palette toggle for light mode + - scheme: default + primary: blue + accent: blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - scheme: slate + primary: blue + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + + font: + text: Roboto + code: Roboto Mono + +plugins: + - search + - autorefs + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - toc: + permalink: true + - tables + - attr_list + - md_in_html + +nav: + - Home: index.md + - Installation: + - installation/index.md + - Development: installation/installation-development.md + - Production: installation/installation-production.md + - Document Storage: installation/document-storage.md + - Load Addresses: installation/load-addresses.md + - Production Setup: installation/prod.md + - Calendar SMS: installation/prod-calendar-sms-sending.md + - MS Graph Configuration: installation/msgraph-configure.md + - Enable Collabora: installation/enable-collabora-for-dev.md + - Development: + - development/index.md + - Access Control: development/access_control_model.md + - API: development/api.md + - Assets: development/assets.md + - Code Quality: development/code-quality.md + - Create Bundle: development/create-a-new-bundle.md + - Cronjobs: development/cronjob.md + - CRUD: development/crud.md + - Database Principles: development/database-principles.md + - Embeddable Comments: development/embeddable-comments.md + - Entity Info: development/entity-info.md + - ESLint: development/es-lint.md + - Exports: development/exports.md + - FAQ: development/FAQ.md + - Forms: development/forms.md + - Localisation: development/localisation.md + - Logging: development/logging.md + - Manual: + - development/manual/index.md + - Routing and Menus: development/manual/routing-and-menus.md + - Menus: development/menus.md + - Messages to Users: development/messages-to-users.md + - Migrations: development/migrations.md + - Pagination: development/pagination.md + - Render Entity: development/render-entity.md + - Routing: development/routing.md + - Run Tests: development/run-tests.md + - Searching: development/searching.md + - Timelines: development/timelines.md + - Useful Snippets: development/useful-snippets.md + - User Interface: + - CSS Classes: development/user-interface/css-classes.md + - JS Functions: development/user-interface/js-functions.md + - Layout Template: development/user-interface/layout-template-usage.md + - Widgets: development/user-interface/widgets.md + - Bundles: + - bundles/index.md + - Activity: bundles/activity.md + - Custom Fields: bundles/custom-fields.md + - Event: bundles/event.md + - Group: bundles/group.md + - LDAP: bundles/ldap.md + - Main: bundles/main.md + - Person: bundles/person.md + - Report: bundles/report.md + +extra: + social: + - icon: fontawesome/brands/gitlab + link: https://gitlab.com/Chill-project + - icon: fontawesome/solid/comments + link: https://app.element.io/#/room/#chill-social-admin:matrix.org diff --git a/docs/requirements.txt b/docs/requirements.txt index a8d979a2b..ccaea4a64 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,4 @@ -docutils==0.13.1 -Pygments==2.2.0 -sphinx==1.8.5 -Jinja2<3.1 -git+https://github.com/fabpot/sphinx-php.git@v2.0.2#egg_name=sphinx-php -jsx-lexer===0.0.8 -sphinx_rtd_theme==0.5.0 +mkdocs>=1.5.0 +mkdocs-material>=9.4.0 +pymdown-extensions>=10.3.0 +mkdocs-autorefs>=0.5.0