Change doc organization to diataxis approach

Author: KybernetikJo

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:

doc/check_names.py

@@ -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 (

doc/create_names_for_reference.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
 

doc/make.bat

@@ -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>`_.