Try add examples

.readthedocs.yaml

@@ -2,7 +2,7 @@
 version: 2
 
 sphinx:
-  configuration: docs/conf.py
+  configuration: example-docs/conf.py
 
 build:
   os: ubuntu-20.04
@@ -15,7 +15,7 @@ python:
     path: .
 
 conda:
-  environment: docs/environment.yml
+  environment: example-docs/environment.yml
 
 submodules:
   include: all

example-docs/Makefile

@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -j auto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	git clone https://github.com/MDAnalysis/mdanalysis.git
+	cp conf.py mdanalysis/package/doc/sphinx/conf.py
+	cd mdanalysis/package/doc/sphinx/ && make html && cd -
+	cp -r mdanalysis/package/doc/html/ mdanalysis-docs/
+
+	# git clone https://github.com/MDAnalysis/UserGuide.git
+
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -j auto $(SPHINXOPTS) $(O)

example-docs/conf.py

@@ -0,0 +1,131 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+
+# -- Project information -----------------------------------------------------
+
+project = "MDAnalysis Sphinx theme"
+html_title = "MDAnalysis Sphinx 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.
+#
+import os
+import sys
+
+copyright = "2023, MDAnalysis"
+author = "MDAnalysis"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "nbsphinx",
+    "mdanalysis_sphinx_theme",
+    "sphinxcontrib.autodoc_pydantic",
+    "sphinx_search.extension",
+]
+
+# Autodoc settings
+autosummary_generate = True
+
+autodoc_default_options = {
+    "members": True,
+    "inherited-members": True,
+    "member-order": "bysource",
+}
+autodoc_preserve_defaults = True
+autodoc_typehints_format = "short"
+# Workaround for autodoc_typehints_format not working for attributes
+# see https://github.com/sphinx-doc/sphinx/issues/10290#issuecomment-1079740009
+python_use_unqualified_type_names = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+napoleon_attr_annotations = True
+napoleon_custom_sections = [("attributes", "params_style")]
+napoleon_use_rtype = False
+napoleon_use_param = True
+napoleon_use_ivar = True
+napoleon_preprocess_types = True
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "mdanalysis_sphinx_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named 'default.css' will overwrite the builtin 'default.css'.
+html_static_path = ["_static"]
+
+# If HTML theme settings isn't lines 90-160, remember to change customization.rst
+
+# -- HTML theme settings ------------------------------------------------
+html_show_sourcelink = True
+html_sidebars = {
+    "**": ["globaltoc.html", "localtoc.html", "searchbox.html"],
+}
+
+# material theme options (see theme.conf for more information)
+html_theme_options = {
+    "base_url": "docs.mdanalysis.org",
+    "repo_url": "https://github.com/mdanalysis/mdanalysis/",
+    "repo_name": "mdanalysis",
+    "mda_official": True,
+}
+
+# If HTML theme settings isn't lines 90-160, remember to change customization.rst
+
+language = "en"
+html_last_updated_fmt = ""
+
+todo_include_todos = True
+
+html_use_index = True
+html_domain_indices = True
+
+nbsphinx_execute = "always"
+nbsphinx_kernel_name = "python3"
+
+extlinks = {
+    "duref": (
+        "http://docutils.sourceforge.net/docs/ref/rst/" "restructuredtext.html#%s",
+        "%s",
+    ),
+    "durole": ("http://docutils.sourceforge.net/docs/ref/rst/" "roles.html#%s", "%s"),
+    "dudir": (
+        "http://docutils.sourceforge.net/docs/ref/rst/" "directives.html#%s",
+        "%s",
+    ),
+}

example-docs/environment.yml

@@ -0,0 +1,78 @@
+name: guide
+channels:
+  - jaimergp/label/unsupported-cudatoolkit-shim
+  - conda-forge
+  - plotly
+  - defaults
+dependencies:
+  # theme
+  - ipykernel
+  - autodoc-pydantic
+  - myst-parser~=1.0
+  - wheel
+  - sphinx-autobuild
+  - sphinx>=6.2.1,<7
+
+
+  # user guide
+  - cython
+  - distributed==2021.1.0
+  - dask==2021.1.0
+  - python-graphviz
+  - pytest
+  - decorator
+  - docutils
+  - graphviz
+  - ipywidgets<8.0.0
+  - ipython
+  - ipygany
+  - jedi
+  - jinja2
+  - jupyter_contrib_nbextensions
+  - matplotlib
+  - nbclient
+  - nbconvert
+  - nbformat
+  - nbsphinx
+  - networkx
+  - nglview
+  - notebook
+  - numpy
+  - packaging
+  - parmed
+  - parso
+  - pip
+  - plotly
+  - pybtex
+  - python=3.9
+  - pyvista
+  - scikit-image
+  - scikit-learn>=1.1.2
+  - sphinxcontrib-bibtex
+  - threadpoolctl
+  - tabulate
+  - widgetsnbextension
+  - ipycytoscape>=1.3.0
+  - seaborn>=0.12.1
+  - openmm>=7.0.0
+  - pandoc
+  - moviepy
+  - ipyvtklink
+  - pip:
+      # theme
+      - readthedocs-sphinx-search
+      - beautifulsoup4
+      - css_html_js_minify
+      - lxml
+      - libsass
+
+      - sphinx_rtd_theme
+      - msmb_theme
+      - sphinx-sitemap
+      - nbval
+      - pre-commit
+      - python-slugify[unidecode]
+      - pyedr>=0.7
+      - git+https://github.com/MDAnalysis/mdanalysis@develop#egg=mdanalysis&subdirectory=package
+      - git+https://github.com/MDAnalysis/mdanalysis@develop#egg=MDAnalysisTests&subdirectory=testsuite
+      - git+https://github.com/MDAnalysis/MDAnalysisData@master#egg=MDAnalysisData

example-docs/index.rst

@@ -0,0 +1,13 @@
+==================================
+MDAnalysis Sphinx theme Quickstart
+==================================
+
+This theme provides a responsive theme for Sphinx documentation by the Open Force Field Initiative.
+It is inspired by `Material for Sphinx <https://bashtage.github.io/sphinx-material/>`_ and `Material for MkDocs <https://squidfunk.github.io/mkdocs-material/>`_, but has been rewritten with the `Bulma <https://bulma.io>`_ CSS framework to remove any JavaScript dependencies.
+
+
+.. toctree::
+    :caption: Examples
+    :maxdepth: 1
+
+    mdanalysis-docs/index

example-docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd