fixed rst preview

.github/holopin.yml

@@ -0,0 +1,5 @@
+organization: mautic
+holobytes:
+  - evolvingStickerId: cm1ti4x4c57560cjq2styaitm
+    icon: avocado
+    alias: writetoberfest-2024

.gitpod.Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11
+
+# Please keep version in sync with the version in .github/workflows/linting.yml for a consistent experience
+ENV VALE_VERSION=3.7.1
+
+WORKDIR /workspace
+
+# Needed for Vale (rst2html) and reStructuredText (rstcheck)
+RUN pip install rst2html rstcheck
+
+RUN mkdir -p vale && cd vale && wget https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz && \
+    tar -xf vale_${VALE_VERSION}_Linux_64-bit.tar.gz && cp /workspace/vale/vale /usr/local/bin/vale && cd ../
+
+# /home/gitpod/.local/bin ensures that Python packages like rstcheck can be found
+ENV PATH=/home/gitpod/.local/bin:$PATH
+
+# Create the gitpod user. UID must be 33333. https://www.gitpod.io/docs/configure/workspaces/workspace-image#use-a-custom-dockerfile
+RUN useradd -l -u 33333 -G sudo -md /home/gitpod -s /bin/bash -p gitpod gitpod
+
+USER gitpod

.gitpod.yml

@@ -1,6 +1,7 @@
 # Since Gitpod doesn't support caching custom Dockerfiles yet, we temporarily
 # use this once which has Python 3.9 and Vale preinstalled.
-image: dennisameling/python-vale:latest
+image: 
+  file: .gitpod.Dockerfile
 
 tasks:
   - before: pip install -r docs/requirements.txt
@@ -9,7 +10,7 @@ tasks:
 vscode:
   extensions:
     - ms-python.python
-    - lextudio.restructuredtext
+    - lextudio.restructuredtext@190.1.4 # See https://github.com/mautic/user-documentation/pull/334#issuecomment-2405922370 before upgrading.
     - trond-snekvik.simple-rst
     - errata-ai.vale-server
     - eamodio.gitlens

.vscode/settings.json

@@ -5,5 +5,8 @@
     "esbonio.sphinx.buildDir": "${workspaceFolder}/build",
     "esbonio.sphinx.confDir": "${workspaceFolder}/docs",
     "restructuredtext.pythonRecommendation.disabled": true,
-    "restructuredtext.preview.name": "sphinx"
-}
+    "restructuredtext.preview.name": "sphinx",
+    "esbonio.sphinx.pythonCommand": "python3",
+    "esbonio.sphinx.buildCommand": "sphinx-build",
+    "esbonio.logging.level": "debug"
+}

docs/conf.py

@@ -58,3 +58,12 @@
 
 # -- Options for EPUB output
 epub_show_urls = 'footnote'
+
+# -- Internationalisation configuration
+
+locale_dirs = ['locale']
+
+# Please add links here that do not pass the "make checklinks" check.
+# A little context on the reason for ignoring is greatly appreciated!
+
+linkcheck_ignore = []

docs/index.rst

@@ -1,4 +1,4 @@
-Mautic community handbook
+Mautic Community Handbook
 #########################
 
 This handbook is a central point of call for understanding the management and organization of the Mautic community.
@@ -9,6 +9,13 @@ The vision is that it grows over time as the teams and governance structure evol
 
    This project is under active development as the handbook is re-platformed from the old system.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Community Handbook
+   :hidden:
+
+   overview/community
+
 .. toctree::
    :maxdepth: 2
    :caption: About Mautic
@@ -24,3 +31,5 @@ The vision is that it grows over time as the teams and governance structure evol
    teams/legal_and_finance_team
 
 
+
+

docs/overview/community.rst

@@ -0,0 +1,6 @@
+Community Handbook
+==================
+
+This handbook is a central point of call for how the Mautic community is organised and managed.
+
+The vision is that it will grow over time as the teams and governance structure evolves, with team members adding useful resources and updating processes as they mature and are refined.

docs/requirements.txt

@@ -7,5 +7,5 @@ readthedocs-sphinx-search==0.3.2
 rstcheck==6.1.1
 myst-parser==1.0.0 
 linkify-it-py==2.0.0
-esbonio==0.16.0
+esbonio==0.16.5
 attrs==22.2.0