Merge pull request #192 from telegraphic/copilot/update-documentation-deployment

Update docs: replace recommonmark with myst-parser, add GitHub Pages CI deployment

Author: telegraphic

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx myst-parser sphinx-rtd-theme
+          pip install -e .
+
+      - name: Copy README as index
+        run: cp README.md docs/source/index.md
+
+      - name: Build HTML docs
+        run: make html
+        working-directory: docs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

.gitignore

@@ -3,4 +3,6 @@
 build/
 dist/
 .DS_Store
-.idea
+.ideahickle.egg-info/
+docs/source/index.md
+docs/build/

docs/source/conf.py

@@ -16,14 +16,11 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-import recommonmark
-from recommonmark.transform import AutoStructify
-
 
 # -- Project information -----------------------------------------------------
 
 project = u'hickle'
-copyright = u'2018-2020, Danny Price, Ellert van der Velden and contributors'
+copyright = u'2018-2025, Danny Price, Ellert van der Velden and contributors'
 author = u'Danny Price'
 
 # The short X.Y version
@@ -44,30 +41,25 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.githubpages',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'myst_parser'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_parsers = {
-   '.md': 'recommonmark.parser.CommonMarkParser',
-}
-source_suffix = ['.rst', '.md']
-#source_suffix = '.rst'
+source_suffix = {'.rst': None, '.md': 'myst'}
 
 # The master toctree document.
-master_doc = '../../README'
+master_doc = 'index'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -84,7 +76,6 @@
 # a list of builtin themes.
 #
 html_theme = "sphinx_rtd_theme"
-html_theme_path = ["_themes", ]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -181,13 +172,3 @@
 
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
-
-
-# -- Extension configuration -------------------------------------------------
-
-def setup(app):
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': lambda url: github_doc_root + url,
-            'auto_toc_tree_section': 'Contents',
-            }, True)
-    app.add_transform(AutoStructify)