diff --git a/doc/make.bat b/doc/make.bat index 2be8306..ac53d5b 100644 --- a/doc/make.bat +++ b/doc/make.bat @@ -1,36 +1,36 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build -set SPHINXPROJ=PackagingScientificPython - -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://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build +set SPHINXPROJ=PackagingScientificPython + +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://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/doc/source/api/diffpy.fourigui.rst b/doc/source/api/diffpy.fourigui.rst index b83d1cb..564ddb3 100644 --- a/doc/source/api/diffpy.fourigui.rst +++ b/doc/source/api/diffpy.fourigui.rst @@ -8,6 +8,12 @@ diffpy.fourigui package :undoc-members: :show-inheritance: +Subpackages +----------- + +.. toctree:: + diffpy.fourigui.example_package + Submodules ---------- diff --git a/doc/source/conf.py b/doc/source/conf.py index 597b0e2..06f8431 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,7 +1,7 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- # -# diffpy.fourigui documentation build configuration file, created by +# diffpy.fourigui documentation build configuration file, created by # noqa: E501 # sphinx-quickstart on Thu Jan 30 15:49:41 2014. # # This file is execfile()d with the current directory set to its @@ -18,9 +18,15 @@ from importlib.metadata import version from pathlib import Path +# Attempt to import the version dynamically from GitHub tag. +try: + fullversion = version("diffpy.fourigui") +except Exception: + fullversion = "No version found. The correct version will appear in the released version." # noqa: E501 + # 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 Path().resolve() to make it absolute, like shown here. +# documentation root, use Path().resolve() to make it absolute, like shown here. # noqa: E501 # sys.path.insert(0, str(Path(".").resolve())) sys.path.insert(0, str(Path("../..").resolve())) sys.path.insert(0, str(Path("../../src").resolve())) @@ -43,6 +49,7 @@ "sphinx.ext.viewcode", "sphinx.ext.intersphinx", "sphinx_rtd_theme", + "sphinx_copybutton", "m2r", ] @@ -90,6 +97,11 @@ # substitute YEAR in the copyright string copyright = copyright.replace("%Y", year) +# For sphinx_copybutton extension. +# Do not copy "$" for shell commands in code-blocks. +copybutton_prompt_text = r"^\$ " +copybutton_prompt_is_regexp = True + # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ["build"] @@ -125,6 +137,14 @@ # html_theme = "sphinx_rtd_theme" +html_context = { + "display_github": True, + "github_user": "diffpy", + "github_repo": "diffpy.fourigui", + "github_version": "main", + "conf_py_path": "/doc/source/", +} + # 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 # documentation. diff --git a/doc/source/index.rst b/doc/source/index.rst index 6f6164e..8ecec60 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -4,19 +4,25 @@ .. |title| replace:: diffpy.fourigui documentation -diffpy.fourigui - Tool for visualizing 3D diffraction and PDF images. +``diffpy.fourigui`` - Tool for visualizing 3D diffraction and PDF images. -| Software version |release|. +| Software version |release| | Last updated |today|. +=============== +Getting started +=============== + +Welcome to the ``diffpy.fourigui`` documentation! + +To get started, please visit the :ref:`Getting started ` page. + ======= Authors ======= -diffpy.fourigui is developed by Billinge Group -and its community contributors. - -For a detailed list of contributors see +``diffpy.fourigui`` is developed by Billinge Group +and its community contributors. For a detailed list of contributors see https://github.com/diffpy/diffpy.fourigui/graphs/contributors. ============ @@ -26,16 +32,23 @@ Installation See the `README `_ file included with the distribution. +================ +Acknowledgements +================ + +``diffpy.fourigui`` is built and maintained with `scikit-package `_. + ================= Table of contents ================= .. toctree:: - :titlesonly: + :maxdepth: 2 + getting-started tutorial - license - release Package API + release + license ======= Indices diff --git a/news/doc.rst b/news/doc.rst new file mode 100644 index 0000000..b0ec659 --- /dev/null +++ b/news/doc.rst @@ -0,0 +1,23 @@ +**Added:** + +* + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* Support ``scikit-package`` Level 5 standard (https://scikit-package.github.io/scikit-package/). + +**Security:** + +*