Merge pull request #61 from venthur/mkdocs

venthur · web-flow · commit e578fb8bd6dd · 2024-05-03T15:50:27.000+02:00
moved from sphinx to mkdocs
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,6 +1,15 @@
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
 python:
-  version: 3.8
   install:
+  - requirements: requirements.txt
+  - requirements: requirements-dev.txt
   - path: .
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [unreleased] - xxxx
 
+* replaced sphinx with mkdocs
+* fixed some documentation issues
 * Added Python 3.12 to test suite
 
 ## [4.0.2] - 2023-10-22
diff --git a/Makefile b/Makefile
@@ -3,8 +3,7 @@ PY = python3
 VENV = venv
 BIN=$(VENV)/bin
 
-DOCS_SRC = docs
-DOCS_OUT = $(DOCS_SRC)/_build
+DOCS_OUT = site
 
 
 ifeq ($(OS), Windows_NT)
@@ -50,7 +49,7 @@ release: $(VENV) build
 
 .PHONY: docs
 docs: $(VENV)
-	$(BIN)/sphinx-build $(DOCS_SRC) $(DOCS_OUT)
+	$(BIN)/mkdocs build
 
 .PHONY: clean
 clean:
diff --git a/README.md b/README.md
@@ -1,9 +1,13 @@
 # python-debianbts
 
-Python-debianbts is a Python library that allows for querying Debian's [Bug
-Tracking System](https://bugs.debian.org). Since 2011, python-debianbts is used
-by Debian's `reportbug` to query the Bug Tracking System and has currently
-(2017-11) roughly [190.000 installations](https://qa.debian.org/popcon.php?package=python-debianbts).
+python-debianbts is a Python library that allows for querying Debian's [Bug
+Tracking System](https://bugs.debian.org) using its SOAP interface. With this
+package you can query for bugs of a particular package, get the status of a bug
+read the messages of bug reports and more.
+
+Since 2011, python-debianbts is used by Debian's `reportbug` to query the Bug
+Tracking System and has currently (2024) roughly [200.000
+installations](https://qa.debian.org/popcon.php?package=python-debianbts).
 
 Online [documentation][] is available on readthedocs.
 
@@ -12,10 +16,14 @@ Online [documentation][] is available on readthedocs.
 
 ## Installing
 
+python-debianbts is available on [Debian][], on every other platform it can be
+installed via pip:
+
 ```bash
 pip install python-debianbts
 ```
 
+[Debian]: https://debian.org
 
 ## Quickstart
 
diff --git a/debianbts/__main__.py b/debianbts/__main__.py
@@ -1,4 +1,4 @@
-"""Entry point for the (not yet implemented cli."""
+"""Entry point for the (not yet implemented) cli."""
 
 
 import logging
diff --git a/debianbts/debianbts.py b/debianbts/debianbts.py
@@ -297,11 +297,12 @@ def get_bug_log(
     """Get Buglogs.
 
     A buglog is a dictionary with the following mappings:
-        * "header" => string
-        * "body" => string
-        * "attachments" => list
-        * "msg_num" => int
-        * "message" => email.message.Message
+
+    * "header": `string`
+    * "body": `string`
+    * "attachments": `list`
+    * "msg_num": `int`
+    * "message": `email.message.Message`
 
     Parameters
     ----------
@@ -374,25 +375,25 @@ def get_bugs(
 
     The conditions are defined by the keyword arguments.
 
-    Arguments
-    ---------
-    kwargs
+    Parameters
+    ----------
+    **kwargs
         Possible keywords are:
-            * "package": bugs for the given package
-            * "submitter": bugs from the submitter
-            * "maint": bugs belonging to a maintainer
-            * "src": bugs belonging to a source package
-            * "severity": bugs with a certain severity
-            * "status": can be either "done", "forwarded", or "open"
-            * "tag": see http://www.debian.org/Bugs/Developer#tags for
-              available tags
-            * "owner": bugs which are assigned to `owner`
-            * "bugs": takes single int or list of bugnumbers, filters the list
-              according to given criteria
-            * "correspondent": bugs where `correspondent` has sent a mail to
-            * "archive": takes a string: "0" (unarchived), "1" (archived) or
-              "both" (un- and archived). if omitted, only returns un-archived
-              bugs.
+
+        * `package`: bugs for the given package
+        * `submitter`: bugs from the submitter
+        * `maint`: bugs belonging to a maintainer
+        * `src`: bugs belonging to a source package
+        * `severity`: bugs with a certain severity
+        * `status`: can be either "done", "forwarded", or "open"
+        * `tag`: see http://www.debian.org/Bugs/Developer#tags for available
+          tags
+        * `owner`: bugs which are assigned to `owner`
+        * `bugs`: takes single int or list of bugnumbers, filters the list
+          according to given criteria
+        * `correspondent`: bugs where `correspondent` has sent a mail to
+        * `archive`: takes a string: "0" (unarchived), "1" (archived) or "both"
+          (un- and archived). if omitted, only returns un-archived bugs.
 
     Returns
     -------
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,5 @@
+::: debianbts.debianbts
+
+::: debianbts.version
+
+::: debianbts.__main__
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,24 @@
+site_name: python-debianbts
+site_url: https://python-debianbts.readthedocs.io/
+repo_url: https://github.com/venthur/python-debianbts
+repo_name: venthur/python-debianbts
+
+nav:
+  - Home: index.md
+  - API: api.md
+
+theme:
+  name: material
+  highlightjs: true
+
+markdown_extensions:
+  - pymdownx.superfences
+
+plugins:
+  - search:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: numpy
+            show_root_heading: true
diff --git a/pyproject.toml b/pyproject.toml
@@ -34,7 +34,9 @@ debianbts = "debianbts.__main__:main"
 [project.optional-dependencies]
 dev = [
     "build",
-    "sphinx",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
     "pytest",
     "pytest-cov",
     "pytest-xdist",
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -1,5 +1,7 @@
 build==1.2.1
-sphinx==7.3.7
+mkdocs==1.6.0
+mkdocs-material==9.5.20
+mkdocstrings[python]==0.25.0
 pytest==8.2.0
 pytest-cov==5.0.0
 pytest-xdist==3.6.1

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""Entry point for the (not yet implemented cli."""`
	`1`	`+"""Entry point for the (not yet implemented) cli."""`
`2`	`2`
`3`	`3`
`4`	`4`	`import logging`