Merge pull request #687 from consideRatio/pr/fix-broken-docs

docs: fix broken api references

.gitignore

@@ -1,3 +1,6 @@
+# Manually added parts to .gitignore
+# ----------------------------------
+#
 # Artifacts from running kubespawner tests with minikube
 bin/
 lib64
@@ -16,17 +19,22 @@ jupyterhub_cookie_secret
 
 # Editors
 .vscode
+.idea
 
+
+# Python .gitignore from https://github.com/github/gitignore/blob/HEAD/Python.gitignore
+# -------------------------------------------------------------------------------------
+#
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
+*$py.class
 
 # C extensions
 *.so
 
 # Distribution / packaging
 .Python
-env/
 build/
 develop-eggs/
 dist/
@@ -38,10 +46,12 @@ lib64/
 parts/
 sdist/
 var/
-venv/
+wheels/
+share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+MANIFEST
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -56,27 +66,122 @@ pip-delete-this-directory.txt
 # Unit test / coverage reports
 htmlcov/
 .tox/
+.nox/
 .coverage
 .coverage.*
 .cache
-.pytest_cache
 nosetests.xml
 coverage.xml
-*,cover
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
 
 # 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/
-docs/source/build/
+docs/_build/
 
 # PyBuilder
+.pybuilder/
 target/
 
-# Pycharm
-.idea/
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .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
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__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/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

docs/Makefile

@@ -1,20 +1,38 @@
-# Minimal makefile for Sphinx documentation
-#
+# Makefile for Sphinx documentation generated by sphinx-quickstart
+# ----------------------------------------------------------------------------
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = Kubespawner
+# 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
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# "make mode" option.
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+
+# Manually added commands
+# ----------------------------------------------------------------------------
+
+# For local development:
+# - builds and rebuilds html on changes to source
+# - starts a livereload enabled webserver and opens up a browser
+devenv:
+	sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+# For local development and CI:
+# - verifies that links are valid
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."

docs/make.bat

@@ -8,29 +8,48 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
-set BUILDDIR=build
-set SPHINXPROJ=Kubespawner
+set BUILDDIR=_build
 
 if "%1" == "" goto help
+if "%1" == "devenv" goto devenv
+if "%1" == "linkcheck" goto linkcheck
+goto default
 
+
+:default
 %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.The 'sphinx-build' command was not found. Open and read README.md!
+	exit /b 1
+)
+%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:help
+%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:devenv
+sphinx-autobuild >NUL 2>NUL
+if errorlevel 9009 (
 	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.The 'sphinx-autobuild' command was not found. Open and read README.md!
 	exit /b 1
 )
+sphinx-autobuild -b html --open-browser "%SOURCEDIR%" "%BUILDDIR%/html" %SPHINXOPTS%
+goto end
+
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+:linkcheck
+%SPHINXBUILD% -b linkcheck "%SOURCEDIR%" "%BUILDDIR%/linkcheck" %SPHINXOPTS%
+echo.
+echo.Link check complete; look for any errors in the above output
+echo.or in "%BUILDDIR%/linkcheck/output.txt".
 goto end
 
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
 
 :end
 popd

docs/source/objects.md

@@ -1,13 +1,13 @@
 # Objects
 
-```{automodule} kubespawner.objects
-
+```{eval-rst}
+.. automodule:: kubespawner.objects
 ```
 
-```{autofunction} make_pod
-
+```{eval-rst}
+.. autofunction:: kubespawner.objects.make_pod
 ```
 
-```{autofunction} make_pvc
-
+```{eval-rst}
+.. autofunction:: kubespawner.objects.make_pvc
 ```

docs/source/reflector.md

@@ -1,9 +1,9 @@
 # Reflectors
 
-```{automodule} kubespawner.reflector
-
+```{eval-rst}
+.. automodule:: kubespawner.reflector
 ```
 
-```{autoclass} kubespawner.reflector.NamespacedResourceReflector
-
+```{eval-rst}
+.. autoclass:: kubespawner.reflector.NamespacedResourceReflector
 ```

docs/source/spawner.md

@@ -1,9 +1,9 @@
 # KubeSpawner
 
-```{automodule} kubespawner
-
+```{eval-rst}
+.. automodule:: kubespawner
 ```
 
-```{autoconfigurable} KubeSpawner
-
+```{eval-rst}
+.. autoconfigurable:: KubeSpawner
 ```

docs/source/utils.md

@@ -1,9 +1,9 @@
 # Utilities
 
-```{automodule} kubespawner.utils
-
+```{eval-rst}
+.. automodule:: kubespawner.utils
 ```
 
-```{autofunction} kubespawner.utils.generate_hashed_slug
-
+```{eval-rst}
+.. autofunction:: kubespawner.utils.generate_hashed_slug
 ```