Add new theme and fix doc building CI (#64)

* use new MDA theme (fix #64 )
* change docs build dir (fix #66 )
* add RTD configuration (fix #65 )

.github/workflows/docs.yml

@@ -14,40 +14,39 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
     - name: Setup python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: 3.9
 
     - name: Display Python version
       run: python -c "import sys; print(sys.version)"
 
-    - name: Install sphinx, pytest, pytest plugins
+    - name: Install deps
       run: |
-        python -m pip install wheel
-        python -m pip install pytest pytest-cov pytest-pep8 pytest-mock codecov
-        python -m pip install sphinx sphinx-sitemap sphinx-rtd-theme
+        python -m pip install "mdanalysis-sphinx-theme>=1.0.1" sphinx-sitemap
 
     - name: Install main dependencies
       run: |
-        python -m pip install six setuptools tqdm
+        python -m pip install tqdm
 
     - name: install package
       run: |
         pip install -v .
 
     - name: build docs
       run: |
-        python setup.py build_sphinx
+        cd docs
+        make html
 
     - name: deploy docs
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./build/sphinx/html
+        publish_dir: ./docs/_build/html
         user_name: 'github-actions'
         user_email: '[email protected]'

.readthedocs.yml

@@ -0,0 +1,26 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "mambaforge-4.10"
+
+# install the repo
+python:
+  install:
+  - method: setuptools
+    path: .
+
+# Optionally set the version of Python and requirements required to build your docs
+conda:
+  environment: environment.yaml

docs/conf.py

@@ -14,8 +14,6 @@
 import sys, os
 import datetime
 
-import sphinx_rtd_theme
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -39,8 +37,7 @@
               'sphinx.ext.mathjax', 'sphinx.ext.viewcode',
               'sphinx.ext.napoleon', 'sphinx.ext.todo',
               'sphinx.ext.autosummary',
-              'sphinx_sitemap',
-              'sphinx_rtd_theme']
+              'sphinx_sitemap']
 
 mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
 
@@ -123,11 +120,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'mdanalysis_sphinx_theme'
 
-html_theme_path = [
-    sphinx_rtd_theme.get_html_theme_path()
-]
+# html_theme_path = []
 
 # 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
@@ -141,20 +136,7 @@
 # /* MDAnalysis white: #FFFFFF */
 # /* MDAnalysis black: #000000 */
 
-html_theme_options = {
-    'canonical_url': '',
-    'logo_only': True,
-    'display_version': True,
-    'prev_next_buttons_location': 'bottom',
-    'style_external_links': False,
-    'style_nav_header_background': 'white',
-    # Toc options
-    'collapse_navigation': True,
-    'sticky_navigation': True,
-    'navigation_depth': 4,
-    'includehidden': True,
-    'titles_only': False,
-}
+html_theme_options = {"mda_official": True}
 
 
 # options common to RTD and MDAnalysis theme
@@ -164,7 +146,7 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 # For RTD theme: custom.css to override theme defaults.
 html_static_path = ['_static']
-html_css_files = ['custom.css']
+# html_css_files = []
 
 
 # The name of an image file (relative to this directory) to place at the top
@@ -174,7 +156,7 @@
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = "_static/logos/mdanalysis-logo.ico"
+# html_favicon = "_static/logos/mdanalysis-logo.ico"
 
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
@@ -305,6 +287,7 @@
 
 # Configuration for intersphinx: refer to the Python standard library
 # and other packages used by MDAnalysis
-intersphinx_mapping = {'https://docs.python.org/': None,
-                       'https://docs.mdanalysis.org/stable': None,
-                       }
+intersphinx_mapping = {
+    "python": ('https://docs.python.org/3/', None),
+    "mdanalysis": ('https://docs.mdanalysis.org/stable', None),
+}

environment.yaml

@@ -0,0 +1,10 @@
+name: mdanalysisdata
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - tqdm
+  - pip
+  - mdanalysis-sphinx-theme >=1.0.1
+  - pip:
+      - sphinx-sitemap