Build and add docs to deb packaging (mamolinux#52)

- Build unix manual from argparse options
- Build html docs from argparse options

debian/control

@@ -7,6 +7,7 @@ Build-Depends: debhelper-compat (= 13),
                python3,
                python3-setuptools,
                python3-sphinx,
+               python3-sphinx-argparse
 Standards-Version: 4.6.0
 Homepage: https://hsbasu.github.io/battery-monitor
 #Vcs-Browser: https://salsa.debian.org/debian/battery-monitor
@@ -22,6 +23,7 @@ Depends: acpi,
          gir1.2-notify-0.7,
          ${python3:Depends},
          ${misc:Depends},
+         ${sphinxdoc:Depends}
 Description: Monitor Laptop Battery
  A utility tool, notifies user about
  charging, discharging and not charging

debian/rules

@@ -7,17 +7,22 @@ export PYBUILD_NAME=battery-monitor
 export PYBUILD_INSTALL_ARGS_python3=--install-scripts=usr/bin
 
 %:
-	dh ${@} --with python3 --buildsystem=pybuild
+	dh ${@} --with python3,sphinxdoc --buildsystem=pybuild
 
 
 # If you need to rebuild the Sphinx documentation
 # Add sphinxdoc to the dh --with line
 #
 # And uncomment the following lines
-#override_dh_auto_build: export http_proxy=127.0.0.1:9
-#override_dh_auto_build: export https_proxy=127.0.0.1:9
+override_dh_auto_build: export http_proxy=127.0.0.1:9
+override_dh_auto_build: export https_proxy=127.0.0.1:9
 override_dh_auto_build:
 	dh_auto_build -O--buildsystem=pybuild
+	PYTHONPATH=. python3 -m sphinx -N -bhtml \
+	docs/ usr/share/html # HTML generator
+	PYTHONPATH=. python3 -m sphinx -N -bman \
+	docs/ usr/share/man/man1 # Manpage generator
+	rm -rfv usr/share/html/.doctrees usr/share/man/man1/.doctrees
 
 override_dh_install:
 	dh_install -O--buildsystem=pybuild

docs/BatteryMonitor.rst

@@ -0,0 +1,7 @@
+Description
+===========
+
+.. argparse::
+   :module: BatteryMonitor.cmd_lines
+   :func: command_line_args
+   :prog: battery-monitor

docs/Makefile

@@ -0,0 +1,20 @@
+# 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
+
+# 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
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,47 @@
+# 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
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../src'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'battery-monitor'
+copyright = 'Copyright (C) 2024 Himadri Sekhar Basu'
+author = 'Himadri Sekhar Basu <[email protected]>'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+	'sphinxarg.ext'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- 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']
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', project, 'Battery Monitor', [author], 1)
+]

docs/index.rst

@@ -0,0 +1,16 @@
+.. Battery Monitor documentation master file, created by
+   sphinx-quickstart on Sun Mar  3 09:21:34 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Battery Monitor's documentation!
+===========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+Indices and tables
+==================

docs/modules.rst

@@ -0,0 +1,7 @@
+Synopsis
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   BatteryMonitor