From 4c41dd26376ec385f15eff14e700099cc1654c5e Mon Sep 17 00:00:00 2001 From: Tom Russell Date: Wed, 4 Sep 2024 10:57:48 +0100 Subject: [PATCH] Update docs build --- docs/Makefile | 7 ++-- docs/make.bat | 70 ++++++++++++++++----------------- docs/source/conf.py | 18 ++++----- docs/source/getting_started.rst | 7 ++-- docs/source/index.rst | 44 ++++++++++++++------- 5 files changed, 82 insertions(+), 64 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index ba501f6..d0c3cbf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,9 +1,10 @@ # Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build diff --git a/docs/make.bat b/docs/make.bat index 4d9eb83..747ffb7 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,35 +1,35 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -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://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 + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py index 276cd84..04b9639 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,7 +16,7 @@ import sys from unittest.mock import MagicMock -from sphinx.apidoc import main as run_apidoc +from sphinx.ext.apidoc import main as run_apidoc __location__ = os.path.abspath(os.path.join(os.path.dirname(__file__))) sys.path.insert(0, os.path.join(__location__, "..", "..", "src")) @@ -66,12 +66,11 @@ def __getattr__(cls, name): run_apidoc( [ - "sphinx-apidoc", - "-M", - "-o", - output_dir, - module_dir, "--force", + "--module-first", + "--output-dir", + output_dir, + module_dir ] ) @@ -80,7 +79,7 @@ def __getattr__(cls, name): # Extra styles, found in _static def setup(app): - app.add_stylesheet("theme_tweaks.css") + app.add_css_file("theme_tweaks.css") # If your documentation needs a minimal Sphinx version, state it here. @@ -93,8 +92,9 @@ def setup(app): extensions = [ "sphinx.ext.autodoc", "sphinx.ext.coverage", + "sphinx.ext.napoleon", "sphinx.ext.viewcode", - "m2r2", + "myst_parser", ] # Add any paths that contain templates here, relative to this directory. @@ -112,7 +112,7 @@ def setup(app): # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index c585ff9..b7c6abc 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -2,6 +2,7 @@ Getting Started =============== -.. mdinclude:: ../../README.md - :start-line: 63 - :end-line: 78 +.. include:: ../../README.md + :parser: myst_parser.sphinx_ + :start-line: 56 + :end-line: 72 diff --git a/docs/source/index.rst b/docs/source/index.rst index efca7e8..349fc7a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,41 +13,57 @@ a spatial networks toolkit :target: https://opensource.org/licenses/MIT :alt: License -.. image:: https://travis-ci.com/tomalrussell/snkit.png?branch=master - :target: https://travis-ci.com/tomalrussell/snkit - :alt: Build Status +.. image:: https://github.com/tomalrussell/snkit/actions/workflows/test.yml/badge.svg + :target: https://github.com/tomalrussell/snkit/actions/workflows/test.yml + :alt: Build .. image:: https://img.shields.io/pypi/v/snkit.svg :target: https://pypi.org/project/snkit/ :alt: PyPI version +.. image:: https://anaconda.org/conda-forge/snkit/badges/version.svg + :target: https://anaconda.org/conda-forge/snkit + :alt: Conda Forge version + +.. image:: https://img.shields.io/badge/poster-10.6084%2Fm9.figshare.11864826.v1-purple + :target: https://doi.org/10.6084/m9.figshare.11864826.v1 + :alt: Poster + +.. image:: https://zenodo.org/badge/129739785.svg + :target: https://doi.org/10.5281/zenodo.3269518 + :alt: DOI + /ˈsnɪkɪt/ – sounds like `[snicket] `_ (noun, Northern English) A narrow passage between houses; an alleyway. Alternatively, a python package to help clean spatial networks data. -.. mdinclude:: ../../README.md +.. include:: ../../README.md + :parser: myst_parser.sphinx_ :start-line: 17 - :end-line: 26 + :end-line: 22 .. image:: _static/unconnected-network.png :alt: Unconnected network -.. mdinclude:: ../../README.md - :start-line: 28 - :end-line: 39 +.. include:: ../../README.md + :parser: myst_parser.sphinx_ + :start-line: 25 + :end-line: 35 .. image:: _static/connected-network.png :alt: Connected network -.. mdinclude:: ../../README.md - :start-line: 41 - :end-line: 59 +.. include:: ../../README.md + :parser: myst_parser.sphinx_ + :start-line: 38 + :end-line: 54 -.. mdinclude:: ../../README.md - :start-line: 78 - :end-line: 107 +.. include:: ../../README.md + :parser: myst_parser.sphinx_ + :start-line: 113 + :end-line: 138 .. toctree::