Patch docs (#14)

* feat: sphinx-gallery initial implementation * test docs deployment * change main to triage * fix: docupdate instead of doc in watchdoc * doc: instruction for developers * fix: docupdate instead of doc in watchdoc * feat: pydata_sphinx_theme * feat: sphinx copybutton * feat: improve documentation * fix: remove separate docs contribution
PyLops · Mar 12, 2023 · 068afa7 · 068afa7
1 parent 3e27fe9
commit 068afa7
Show file tree

Hide file tree

Showing 21 changed files with 522 additions and 107 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,140 @@
+curvelops/_version.py
+
+# Documentation
+docssrc/build
+docssrc/source/api/generated
+docssrc/source/gallery
+
+# Editors
+.*.sw[po]
+.vscode/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
diff --git a/Makefile b/Makefile
@@ -34,16 +34,6 @@ tests:
 	make pytestcheck
 	$(PYTEST) tests
 
-doc:
-	cd docs && rm -rf build && sphinx-apidoc -f -M -o source/ ../curvelops && make html && cd -
-	# Add -P to sphinx-apidoc to include private files
-
-watchdoc:
-	while inotifywait -q -r curvelops/ -e create,delete,modify; do { make doc; }; done
-
-servedoc:
-	$(PYTHON) -m http.server --directory docs/build/html/
-
 lint:
 	flake8 docs/ curvelops/ tests/
 
@@ -52,3 +42,27 @@ typeannot:
 
 coverage:
 	coverage run -m pytest && coverage xml && coverage html && $(PYTHON) -m http.server --directory htmlcov/
+
+watchdoc:
+	make doc && while inotifywait -q -r curvelops/ docssrc/source/ -e create,delete,modify; do { make docupdate; }; done
+
+servedoc:
+	$(PYTHON) -m http.server --directory docssrc/build/html/
+
+doc:
+    # Add after rm: sphinx-apidoc -f -M -o source/ ../curvelops
+    # Use -O to include private files
+	cd docssrc  && rm -rf source/api/generated && rm -rf source/gallery &&\
+	rm -rf source/tutorials && rm -rf source/examples &&\
+	rm -rf build && make html && cd ..
+
+docupdate:
+	cd docssrc && make html && cd ..
+
+docgithub:
+	cd docssrc && make github && cd ..
+
+docpush:
+	git checkout gh-pages && git merge main && cd docssrc && make github &&\
+	cd ../docs && git add . && git commit -m "Updated documentation" &&\
+	git push origin gh-pages && git checkout main
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/source/curvelops.plot.rst b/docs/source/curvelops.plot.rst
diff --git a/docs/source/curvelops.rst b/docs/source/curvelops.rst
diff --git a/docs/source/curvelops.typing.rst b/docs/source/curvelops.typing.rst
diff --git a/docs/source/curvelops.utils.rst b/docs/source/curvelops.utils.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
diff --git a/docs/Makefile → docssrc/Makefile b/docs/Makefile → docssrc/Makefile
@@ -1,9 +1,13 @@
 # Minimal makefile for Sphinx documentation
 #
 
+# Disable numba
+# export NUMBA_DISABLE_JIT=1
+
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = curvelops
 SOURCEDIR     = source
 BUILDDIR      = build
 
@@ -16,4 +20,9 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Make for github pages
+github:
+	@make html
+	@cp -a build/html/. ../docs
diff --git a/docs/source/conf.py → docssrc/source/conf.py b/docs/source/conf.py → docssrc/source/conf.py
@@ -16,6 +16,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from sphinx_gallery.sorting import ExampleTitleSortKey
+
 from curvelops import __version__ as version
 
 release = version
@@ -43,6 +45,8 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
+    "sphinx_gallery.gen_gallery",
+    "sphinx_copybutton",
 ]
 
 # intersphinx configuration
@@ -85,7 +89,7 @@
 # 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 = "pydata_sphinx_theme"
 
 # 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
@@ -191,3 +195,29 @@
 
 # -- Extension configuration -------------------------------------------------
 autodoc_typehints = "none"
+
+sphinx_gallery_conf = {
+    "examples_dirs": "../../examples",  # path to your example scripts
+    "gallery_dirs": "gallery",  # path to where to save gallery generated output
+    "filename_pattern": r"\.py",
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example by file name instead of number of lines (default)
+    "within_subsection_order": ExampleTitleSortKey,
+    # directory where function granular galleries are stored
+    "backreferences_dir": "api/generated/backreferences",
+    # Modules for which function level galleries are created.
+    "doc_module": "curvelops",
+    # Insert links to documentation of objects in the examples
+    "reference_url": {"curvelops": None},
+}
+# Always show the source code that generates a plot
+plot_include_source = True
+plot_formats = ["png"]
+# Sphinx project configuration
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "**.ipynb_checkpoints", "**.ipynb", "**.md5"]
+source_suffix = ".rst"
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True