split config

add more on contributing page
simplify .env file

Author: NicolasMassart

Diff for: .env

@@ -1,17 +1,9 @@
 DOCTOOLS_IMAGE_VERSION=latest
 PROJECT=doctools
 LANGUAGE=en
-LATEST_VERSION=latest
-STABLE_VERSION=stable
 SOURCE_DIR=site
+
+#VERSION_SWITCH=true
+
 AWS_S3_BUCKET=docshosting
 AWS_REGION=us-east-2
-GTM_ID=GTM-PBFNGBR
-SITE_NAME=Doctools
-SITE_DESCRIPTION="Doctools documentation template"
-REPOS_NAME=Consensys/doctools.template-site
-REPOS_URL=https://github.com/Consensys/doctools.template-site
-SOCIAL_DISCORD=https://discord.gg/5U9Jwp7
-SOCIAL_EMAIL=mailto:[email protected]
-SOCIAL_WEB=https://consensys.net/docs/
-#VERSION_SWITCH=true

Diff for: docs/howto/advanced/contributing.md

@@ -20,6 +20,9 @@ To get the best from the system, consider having the following settings[^1]:
 - 6GB RAM
 - 1GB swap
 
+!!! warning
+    If you are using a macOS machine, do not activate the experimental Docker Desktop "Use the new Virtualization framework". It will slow down builds by at least 3 times. A normal build time is around 5 seconds for this website for instance.
+
 [^1]:
     These settings were tested on a MacBook Pro (15-inch, 2018) - 2,6 GHz 6-Core Intel Core i7 - 16 GB 2400 MHz DDR4.
 
@@ -88,12 +91,15 @@ Create a new file in your `doctools.template-site` directory with the following
     version: '3.2'
     services:
       mkdocs:
-        container_name: mkdocs-serve-dev-${PROJECT:-project}-${LANGUAGE:-en}
+        container_name: mkdocs-serve-dev-${PROJECT:-project}
         ports:
           - "0.0.0.0:8000:8000"
-        image: ghcr.io/consensys/doctools-builder:${DOCTOOLS_IMAGE_VERSION:-latest}
+        image: ghcr.io/consensys/doctools-builder:${DOCTOOLS_IMAGE_VERSION:-dev}
+        build:
+          context: ../doctools.action-builder/
         working_dir: /workspace/
         env_file: .env.dev
+        command: ["serve", "--watch-theme" ,"--dev-addr", "0.0.0.0:8000"]
         volumes:
           - type: bind
             source: .
@@ -115,34 +121,36 @@ Copy your `.env` file to a `.env.dev` file
 To preview the doc site locally, go to your doc site code source directory and run:
 
 ```bash
-docker compose -f docker-compose.dev.yml up-d
+docker compose -f docker-compose.dev.yml --env-file ./.env.dev up
 ```
 
 Then open [`http://0.0.0.0:8000`](http://0.0.0.0:8000){: target="_blank} in your browser and navigate the preview.
 
 ### Stropping the preview
 
-To stop and remove containers, run
+To stop the service, type ++ctrl+c++ and then remove containers by running
+
 ```bash
-docker compose -f docker-compose.dev.yml down
+docker compose down mkdocs
 ```
 
 ### Reloading on changes
 
-If you keep the Docker compose service running in background,
+If you keep the Docker compose service running,
 the website preview will reload and display changes automatically for:
 
 - content (all `.md` files, modification, deletions or new pages if added to navigation)
-- configuration (changes on entries in `mkdocs.yml`)
+- configuration (changes on entries in `mkdocs.yml` and all `mkdocs.*.yml`)
+- theme templates (in the ``../doctools.action-builder/common/custom_theme` directory)
 
 !!!important
-    If you make changes on the `.env.dev` or any HTML template file or assets outside of your repos `docs` folder,
+    If you make changes on the `.env.dev` or assets outside of your repos `docs` folder,
     the system is not yet able to reload automatically and you will have to restart the docker-compose service.
 
     Run:
 
     ```bash
-    docker compose -f docker-compose.dev.yml restart
+    docker compose restart mkdocs
     ```
 
 [Doctools action builder]: https://github.com/ConsenSys/doctools.action-builder

Diff for: docs/howto/advanced/extra-configuration.md

@@ -0,0 +1,6 @@
+---
+title: Extra configuration
+description: How to configure Doctools site extra values with YAML and .env files.
+---
+
+# Extra configuration

Diff for: mkdocs.exclude.yml

@@ -12,8 +12,7 @@
 
 # This configuration must inherit the base configuration file available in the Doctools docker image.
 # See source at https://github.com/ConsenSys/doctools.action-builder/blob/main/common/custom_theme/base.yml
-# Do not modify this INHERIT line.
-INHERIT: /common/custom_theme/base.yml
+INHERIT: /common/custom_theme/base.yml # DO NOT MODIFY THIS LINE
 
 plugins:
   exclude:

Diff for: mkdocs.extra.yml

@@ -12,16 +12,25 @@
 
 # This configuration must inherit the base configuration file available in the Doctools docker image.
 # See source at https://github.com/ConsenSys/doctools.action-builder/blob/main/common/custom_theme/base.yml
-# Do not modify this INHERIT line.
-INHERIT: mkdocs.exclude.yml
+INHERIT: mkdocs.exclude.yml # DO NOT MODIFY THIS LINE
 
+# Extra data configures some specific aspect of the theme.
+# You can find a full description of the values in the Doctool doc site:
+# https://consensys.net/docs/doctools/en/latest/howto/advanced/extra-configuration
 extra:
-  support: /support/
-  inverted_logo: 'assets/logo_inverted.svg'
+  support: /support/ # The path to the default support page, for instance displayed in 404 pages
+  inverted_logo: 'assets/logo_inverted.svg' # Path for a colour inverted logo, for instance displayed in 404 pages
   # Announce can contain HTML but limit it to small images or links. NO BIG DIRTY HACKS PLEASE.
   # If announce is removed or commented, the banner will be hidden
   announce: 'Improved version of the Consensys doc system, read about the new features!'
-  # If languages are removed, commented or only contain one language, the language switch will be hidden
-#  languages:
-#    en: English (en)
-#    zh: 中文 (zh)
+  logo_is_text: false # indicates if logo is using text or is only a shape and if we have to add the project name as text.
+  analytics: # information for Analytics. Default is Google Tag manager.
+    gtmid: GTM-PBFNGBR
+  social: # list of social media links and icons to display ion the pages footer.
+  # See https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/?h=social#configuration
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/5U9Jwp7
+    - icon: fontawesome/solid/envelope
+      link: mailto:[email protected]
+    - icon: material/web
+      link: https://consensys.net/quorum/developers

Diff for: mkdocs.navigation.yml

@@ -0,0 +1,38 @@
+---
+# Copyright 2021 ConsenSys Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+# This configuration must inherit the base configuration file available in the Doctools docker image.
+# See source at https://github.com/ConsenSys/doctools.action-builder/blob/main/common/custom_theme/base.yml
+INHERIT: mkdocs.extra.yml # DO NOT MODIFY THIS LINE
+
+nav:
+  - Overview: index.md
+  - New features: changelog.md
+  - Getting started: getting_started.md
+  - How To:
+      - howto/index.md
+      - Create a new doc site: howto/setup_new_doc_repos.md
+      - Configure MkDocs: howto/configure_mkdocs.md
+      - Preview the doc site:
+        - howto/preview_the_doc_site/index.md
+        - Doc preview demo: howto/preview_the_doc_site/demo.md
+      - Publish the doc site: howto/publish_the_doc_site.md
+      - Advanced use:
+        - Contribute to Doctools: howto/advanced/contributing.md
+        - Extra configuration: howto/advanced/extra-configuration.md
+  - Examples:
+    - examples/index.md
+    - CLI reference: examples/write_cli_reference.md
+    - API reference: examples/write_rest_api_reference.md
+    - Support page: examples/support.md
+  - Reference:
+      - MarkDown syntax: reference/markdown.md

Diff for: mkdocs.redirects.yml

@@ -12,9 +12,10 @@
 
 # This configuration must inherit the base configuration file available in the Doctools docker image.
 # See source at https://github.com/ConsenSys/doctools.action-builder/blob/main/common/custom_theme/base.yml
-# Do not modify this INHERIT line.
-INHERIT: mkdocs.extra.yml
+INHERIT: mkdocs.navigation.yml # DO NOT MODIFY THIS LINE
 
+# Configure redirects.
+# All page removed or with changed path (moved in another directory) has to be redirected here.
 plugins:
   redirects:
     redirect_maps:

Diff for: mkdocs.theme.yml

@@ -0,0 +1,30 @@
+---
+# Copyright 2021 ConsenSys Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+# This configuration must inherit the base configuration file available in the Doctools docker image.
+# See source at https://github.com/ConsenSys/doctools.action-builder/blob/main/common/custom_theme/base.yml
+INHERIT: mkdocs.redirects.yml # DO NOT MODIFY THIS LINE
+
+theme:
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: consensys
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: consensys-dark
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+  logo: 'assets/logo.svg'
+  favicon: 'assets/favicon.svg'

Diff for: mkdocs.yml

@@ -12,27 +12,16 @@
 
 # This configuration must inherit the base configuration file available in the Doctools docker image.
 # See source at https://github.com/ConsenSys/doctools.action-builder/blob/main/common/custom_theme/base.yml
-# Do not modify this INHERIT line.
-INHERIT: mkdocs.redirects.yml
+INHERIT: mkdocs.theme.yml # DO NOT MODIFY THIS LINE
 
-nav:
-  - Overview: index.md
-  - New features: changelog.md
-  - Getting started: getting_started.md
-  - How To:
-      - howto/index.md
-      - Create a new doc site: howto/setup_new_doc_repos.md
-      - Configure MkDocs: howto/configure_mkdocs.md
-      - Preview the doc site:
-        - howto/preview_the_doc_site/index.md
-        - Doc preview demo: howto/preview_the_doc_site/demo.md
-      - Publish the doc site: howto/publish_the_doc_site.md
-      - Advanced use:
-        - Contribute to Doctools: howto/advanced/contributing.md
-  - Examples:
-    - examples/index.md
-    - CLI reference: examples/write_cli_reference.md
-    - API reference: examples/write_rest_api_reference.md
-    - Support page: examples/support.md
-  - Reference:
-      - MarkDown syntax: reference/markdown.md
+# Project information
+site_name: Doctools
+site_description: Doctools documentation template
+
+# Software Repository
+repo_name: Consensys/doctools.template-site
+repo_url: https://github.com/Consensys/doctools.template-site
+
+# Project information
+site_author: ConsenSys
+copyright: This documentation is hosted by <a href="https://consensys.net/">ConsenSys</a> and licensed under Apache 2.0 license