readthedocs initial setup - long overdue

Author: mahtin

.gitignore

@@ -48,7 +48,8 @@ coverage.xml
 *.log
 
 # Sphinx documentation
-docs/_build/
+docs/*.rst
+docs/_build/*
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/requirements.txt
+  - requirements: requirements.txt
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py

Makefile

@@ -102,6 +102,13 @@ sign:
 	ls -l tarball/$$v.tar.gz tarball/$$v.zip ; \
 	ls -l tarball/$$v.tar.gz.asc tarball/$$v.zip.asc ;
 
+docs: all
+	sphinx-apidoc -Mfe -o docs . setup.py
+	sphinx-build -j auto -b html docs docs/_build/html
+
+clean-docs: all
+	rm -rf docs/*.rst docs/_build/
+
 lint:
 	$(PYLINT) CloudFlare cli4
 

docs/Makefile

@@ -0,0 +1,23 @@
+#
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+STATICDIR     = _static
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.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).
+%: Makefile
+	mkdir -p ${BUILDDIR} ${STATICDIR}
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import re
+with open('../CloudFlare/__init__.py', 'r') as f:
+    _version_re = re.compile(r"__version__\s=\s'(.*)'")
+    version = _version_re.search(f.read()).group(1)
+
+project = 'python-cloudflare'
+copyright = 'Cloudflare (c) 2016 thru 2024'
+author = 'Martin J Levy'
+release = str(version)
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+    'sphinx_rtd_theme',
+]
+
+html_theme = "sphinx_rtd_theme"
+
+templates_path = ['_templates']
+exclude_patterns = [
+    'CloudFlare/__init__.py',
+    'CloudFlare/tests/__init__.py',
+    '_build',
+    'Thumbs.db',
+    '.DS_Store'
+]
+
+autoclass_content = 'both'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))

docs/index.rst

@@ -0,0 +1,20 @@
+.. python-cloudflare documentation master file, created by
+   sphinx-quickstart on Fri Mar  1 09:53:57 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to python-cloudflare's documentation!
+=============================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. include:: modules.rst
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=4.0.0
+myst_parser>=1.0.0
+sphinx_rtd_theme>=1.2.0