Change doc organization to diataxis approach

python-control · Jan 18, 2024 · ffb0916 · ffb0916
1 parent 396f287
commit ffb0916
Show file tree

Hide file tree

Showing 20 changed files with 297 additions and 184 deletions.
diff --git a/doc/Makefile b/doc/Makefile
@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:

diff --git a/doc/check_names.py b/doc/check_names.py
diff --git a/doc/create_names_for_reference.py b/doc/create_names_for_reference.py
diff --git a/doc/make.bat b/doc/make.bat
@@ -7,8 +7,8 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=.
-set BUILDDIR=_build
+set SOURCEDIR=source
+set BUILDDIR=build
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (

diff --git a/doc/conf.py → doc/source/conf.py b/doc/conf.py → doc/source/conf.py
@@ -5,14 +5,11 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../slycot'))
 
-import subprocess
-subprocess.run(["python", "check_names.py"])
-
+master_doc = "index"
 from datetime import date
 project = 'Slycot'
 copyright = f'{date.today().year}, Slycot Developers'
@@ -29,7 +26,6 @@
 
 print("version %s, release %s" % (version, release))
 
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 

diff --git a/doc/source/dev/contributing.rst → doc/source/contributing/index.rst b/doc/source/dev/contributing.rst → doc/source/contributing/index.rst
@@ -1,10 +1,12 @@
-**********************
-Contributing to Slycot
-**********************
+.. this page is referenced from the front page but it's unnecessary as a navigation section for now.
+
+:orphan:
 
+Contributing to Slycot
+======================
 
 Development process and tools
-=============================
+-----------------------------
 
 The development process is currently described on the `slycot github repo <https://github.com/python-control/Slycot>`_ and the `slycot github wiki <https://github.com/python-control/Slycot/wiki>`_.
 You should be familiar with following topics:
@@ -17,13 +19,12 @@ You should be familiar with following topics:
 - `f2py <https://numpy.org/devdocs/f2py/index.html>`_
 
 numpydoc
-========
+--------
 
 Slycot uses numpydoc for the docstring style in order to provide support the Numpy docstring format in sphinx,
 `see numpydoc example <https://numpydoc.readthedocs.io/en/latest/example.html>`_.
 
 F2PY
-====
+----
 
-Slycot heavily relias on `F2PY <https://numpy.org/devdocs/f2py/index.html>`_.
-`F2PY`_ is currently a part of `NumPy <http://www.numpy.org>`_.
+Slycot heavily relias on `F2PY <https://numpy.org/devdocs/f2py/index.html>`_, which is currently a part of `NumPy <http://www.numpy.org>`_.
diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst
diff --git a/doc/source/examples/ab13dd_nb.ipynb b/doc/source/examples/ab13dd_nb.ipynb
diff --git a/doc/source/examples/ad13dd_example.rst b/doc/source/examples/ad13dd_example.rst
diff --git a/doc/source/examples/index.rst b/doc/source/examples/index.rst
diff --git a/doc/source/explanation/index.rst b/doc/source/explanation/index.rst
@@ -0,0 +1,12 @@
+.. this page is referenced from the front page but it's unnecessary as a navigation section for now.
+
+:orphan:
+
+Inspect
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   inspect_slycot
+   inspect_slicot_slycot
diff --git a/doc/source/dev/inspect_slicot_slycot.ipynb → ...e/explanation/inspect_slicot_slycot.ipynb b/doc/source/dev/inspect_slicot_slycot.ipynb → ...e/explanation/inspect_slicot_slycot.ipynb
diff --git a/doc/source/dev/inspect_slycot.ipynb → doc/source/explanation/inspect_slycot.ipynb b/doc/source/dev/inspect_slycot.ipynb → doc/source/explanation/inspect_slycot.ipynb
diff --git a/doc/source/dev/slicot_routines.txt → doc/source/explanation/slicot_routines.txt b/doc/source/dev/slicot_routines.txt → doc/source/explanation/slicot_routines.txt