From b8af00f370845aaec5071ddb6e25207fd4848f58 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Thu, 10 Aug 2023 21:56:38 +1000 Subject: [PATCH 1/3] try add examples --- .readthedocs.yaml | 4 +- example-docs/Makefile | 27 ++++++++ example-docs/conf.py | 131 +++++++++++++++++++++++++++++++++++ example-docs/environment.yml | 61 ++++++++++++++++ example-docs/index.rst | 13 ++++ example-docs/make.bat | 35 ++++++++++ 6 files changed, 269 insertions(+), 2 deletions(-) create mode 100644 example-docs/Makefile create mode 100644 example-docs/conf.py create mode 100644 example-docs/environment.yml create mode 100644 example-docs/index.rst create mode 100644 example-docs/make.bat diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d5c2583..b8d9db2 100644 --- a/.readthedocs.yaml +++ b/.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 \ No newline at end of file diff --git a/example-docs/Makefile b/example-docs/Makefile new file mode 100644 index 0000000..2c6b4e5 --- /dev/null +++ b/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) diff --git a/example-docs/conf.py b/example-docs/conf.py new file mode 100644 index 0000000..853bb61 --- /dev/null +++ b/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", + ), +} diff --git a/example-docs/environment.yml b/example-docs/environment.yml new file mode 100644 index 0000000..e372818 --- /dev/null +++ b/example-docs/environment.yml @@ -0,0 +1,61 @@ +name: guide +channels: + - jaimergp/label/unsupported-cudatoolkit-shim + - conda-forge + - plotly + - defaults +dependencies: + - 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 + - sphinx + - sphinxcontrib-bibtex + - threadpoolctl + - tabulate + - widgetsnbextension + - ipycytoscape>=1.3.0 + - seaborn>=0.12.1 + - openmm>=7.0.0 + - pandoc + - moviepy + - ipyvtklink + - pip: + - sphinx_rtd_theme + - msmb_theme + - sphinx-sitemap + - nbval + - pre-commit + - 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 \ No newline at end of file diff --git a/example-docs/index.rst b/example-docs/index.rst new file mode 100644 index 0000000..3da2525 --- /dev/null +++ b/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 `_ and `Material for MkDocs `_, but has been rewritten with the `Bulma `_ CSS framework to remove any JavaScript dependencies. + + +.. toctree:: + :caption: Examples + :maxdepth: 1 + + mdanalysis-docs/index \ No newline at end of file diff --git a/example-docs/make.bat b/example-docs/make.bat new file mode 100644 index 0000000..1264db8 --- /dev/null +++ b/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 From 95733d9424cf2785b74824c10faaa731d2a80cf1 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Thu, 10 Aug 2023 22:11:12 +1000 Subject: [PATCH 2/3] flesh out env --- example-docs/environment.yml | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/example-docs/environment.yml b/example-docs/environment.yml index e372818..2258694 100644 --- a/example-docs/environment.yml +++ b/example-docs/environment.yml @@ -5,6 +5,16 @@ channels: - 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 @@ -38,7 +48,6 @@ dependencies: - pyvista - scikit-image - scikit-learn>=1.1.2 - - sphinx - sphinxcontrib-bibtex - threadpoolctl - tabulate @@ -50,6 +59,13 @@ dependencies: - moviepy - ipyvtklink - pip: + # theme + - readthedocs-sphinx-search + - beautifulsoup4 + - css_html_js_minify + - lxml + - libsass + - sphinx_rtd_theme - msmb_theme - sphinx-sitemap From 0e997c076a3465e0f4da3d93212b2301452f4772 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Fri, 11 Aug 2023 06:11:14 +1000 Subject: [PATCH 3/3] add slugify --- example-docs/environment.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/example-docs/environment.yml b/example-docs/environment.yml index 2258694..708660a 100644 --- a/example-docs/environment.yml +++ b/example-docs/environment.yml @@ -71,6 +71,7 @@ dependencies: - 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