From 7603b119d27c130ed1c71ba7d8153fcb104974f0 Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Fri, 23 Aug 2024 15:54:17 -0600 Subject: [PATCH] doc tools, SECURITY.md updates --- SECURITY.md | 6 ++++-- docs/Makefile | 29 ----------------------------- docs/TODO.md | 4 ++-- docs/conf.py | 9 +++++---- pdm.lock | 49 +++++++++++++++++++++++++++++++------------------ pyproject.toml | 9 +++++---- 6 files changed, 47 insertions(+), 59 deletions(-) delete mode 100644 docs/Makefile diff --git a/SECURITY.md b/SECURITY.md index 3c8974a..0b02f73 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,8 +4,10 @@ | Version | Supported | | ---------- | ------------------ | -| 0.8.x | :white_check_mark: | -| <= 0.7.x | :x: | +| 1.0.x | :white_check_mark: Yes | +| 0.9.x | :heavy_exclamation_mark: Maintenance mode, security or major bug fixes only | +| 0.8.x | :x: No longer supported | | +| <= 0.7.x | :x: No longer supported | ## Reporting a Vulnerability or other security issue diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index a1f1156..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -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 man clean - -# 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) - -# Generate Unix manual page -man: - mkdir -p ./_build/man - $(SPHINXBUILD) -b man . ./_build/man - mv ./_build/man/getmac.1 . - rm -Rf ./_build/man - -clean: - rm -rf ./_build/* diff --git a/docs/TODO.md b/docs/TODO.md index b0a0a57..f76dad3 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -12,7 +12,7 @@ - [x] Document `initialize_method_cache()` - [ ] Auto-generated API docs - [x] Add docstrings to all util methods -- [ ] Furo, sphinx-autodoc-typehints, sphinx-argparse-cli, sphinx-automodapi, sphinx-copybutton, recommonmark +- [x] Furo, sphinx-autodoc-typehints, sphinx-argparse-cli, sphinx-automodapi, sphinx-copybutton, recommonmark ## Tests - [ ] Add test to ensure only the expected files make it into the sdist and wheel, no unexpected files @@ -62,7 +62,7 @@ ## Before releasing - [ ] Add a deprecation warning to `get-mac` package, don't publish it for 1.0.0 -- [ ] Update supported versions table in [SECURITY.md](../SECURITY.md) +- [x] Update supported versions table in [SECURITY.md](../SECURITY.md) - [ ] Automate publishing to PyPI+GitHub Release in GitHub Actions - [ ] Edit README.md to append CHANGELOG before publishing to PyPI diff --git a/docs/conf.py b/docs/conf.py index 0f6a93e..da216e0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,13 +32,14 @@ # -- General configuration --------------------------------------------------- -# TODO: sphinx-copybutton -# TODO: sphinx-tabs (or another extension) to provide tabbed command -# examples for different platforms (e.g. for developer docs and CLI usage) -# TODO(python3): sphinx-autodoc-typehints extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', + 'sphinx_autodoc_typehints', + 'sphinx_inline_tabs', + 'sphinx_copybutton', + 'sphinx_argparse_cli', + 'sphinx_automodapi.automodapi', ] # TODO: setup ReadTheDocs diff --git a/pdm.lock b/pdm.lock index 8d1a5ee..776f822 100644 --- a/pdm.lock +++ b/pdm.lock @@ -5,7 +5,7 @@ groups = ["default", "docs", "lint", "test"] strategy = ["inherit_metadata"] lock_version = "4.5.0" -content_hash = "sha256:6a3e317605acee0e758af573b6bbaf9f93490f1ac59af17dd6c84b58c914dd58" +content_hash = "sha256:3566b05c118d1c7d67c5cb4ebf1289de02748b7031a2f20d5cd505b293efd47b" [[metadata.targets]] requires_python = "~=3.8" @@ -873,6 +873,21 @@ files = [ {file = "sphinx-6.2.1-py3-none-any.whl", hash = "sha256:97787ff1fa3256a3eef9eda523a63dbf299f7b47e053cfcf684a1c2a8380c912"}, ] +[[package]] +name = "sphinx-argparse-cli" +version = "1.11.0" +requires_python = ">=3.7" +summary = "render CLI arguments (sub-commands friendly) defined by argparse module" +groups = ["docs"] +marker = "python_version >= \"3.9\"" +dependencies = [ + "sphinx!=6.1,>=5.3", +] +files = [ + {file = "sphinx_argparse_cli-1.11.0-py3-none-any.whl", hash = "sha256:a0a2a153816487d2151c47f2d496ed714b040226a3dcd0f66ff823c6497ae3cd"}, + {file = "sphinx_argparse_cli-1.11.0.tar.gz", hash = "sha256:03e5012ea8456a29aa45ae4583c74b8be8733ea0a6f515e6beff4fb6a1242ec2"}, +] + [[package]] name = "sphinx-autodoc-typehints" version = "1.23.0" @@ -888,6 +903,21 @@ files = [ {file = "sphinx_autodoc_typehints-1.23.0.tar.gz", hash = "sha256:5d44e2996633cdada499b6d27a496ddf9dbc95dd1f0f09f7b37940249e61f6e9"}, ] +[[package]] +name = "sphinx-automodapi" +version = "0.17.0" +requires_python = ">=3.8" +summary = "Sphinx extension for auto-generating API documentation for entire modules" +groups = ["docs"] +marker = "python_version >= \"3.9\"" +dependencies = [ + "sphinx>=4", +] +files = [ + {file = "sphinx-automodapi-0.17.0.tar.gz", hash = "sha256:7ccdadad57add4aa9149d9f2bb5cf28c8f8b590280b4735b1156ea8355c423a1"}, + {file = "sphinx_automodapi-0.17.0-py3-none-any.whl", hash = "sha256:4d029cb79eef29413e94ab01bb0177ebd2d5ba86e9789b73575afe9c06ae1501"}, +] + [[package]] name = "sphinx-basic-ng" version = "1.0.0b2" @@ -933,23 +963,6 @@ files = [ {file = "sphinx_inline_tabs-2022.1.2b11.tar.gz", hash = "sha256:afb9142772ec05ccb07f05d8181b518188fc55631b26ee803c694e812b3fdd73"}, ] -[[package]] -name = "sphinx-tabs" -version = "3.4.5" -requires_python = "~=3.7" -summary = "Tabbed views for Sphinx" -groups = ["docs"] -marker = "python_version >= \"3.9\"" -dependencies = [ - "docutils", - "pygments", - "sphinx", -] -files = [ - {file = "sphinx-tabs-3.4.5.tar.gz", hash = "sha256:ba9d0c1e3e37aaadd4b5678449eb08176770e0fc227e769b6ce747df3ceea531"}, - {file = "sphinx_tabs-3.4.5-py3-none-any.whl", hash = "sha256:92cc9473e2ecf1828ca3f6617d0efc0aa8acb06b08c56ba29d1413f2f0f6cf09"}, -] - [[package]] name = "sphinxcontrib-applehelp" version = "2.0.0" diff --git a/pyproject.toml b/pyproject.toml index c343695..fc088ee 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -102,10 +102,11 @@ docs = [ "furo; python_version >= \"3.9\"", "sphinx<7.0.0,>=6.1.3; python_version >= \"3.9\"", "recommonmark<1.0.0,>=0.7.1; python_version >= \"3.9\"", - "sphinx-autodoc-typehints<2.0.0,>=1.21.8; python_version >= \"3.9\"", - "sphinx-copybutton<1.0.0,>=0.5.1; python_version >= \"3.9\"", - "sphinx-inline-tabs<2023.0.0,>=2022.1.2b11; python_version >= \"3.9\"", - "sphinx-tabs<4.0.0,>=3.4.1; python_version >= \"3.9\"", + "sphinx-autodoc-typehints; python_version >= \"3.9\"", + "sphinx-copybutton; python_version >= \"3.9\"", + "sphinx-inline-tabs; python_version >= \"3.9\"", + "sphinx-argparse-cli; python_version >= \"3.9\"", + "sphinx-automodapi; python_version >= \"3.9\"", ] [tool.pdm.build]