Add auto-generated API documention (pypa#810)

* Add API docs Via `sphinx-apidoc -T -M -e -o docs/api twine` * Update autodoc configuration * Silence Sphinx build errors * Move apidoc to internal directory * Add warning re: public API * Flatten toctree
bhrutledge · Sep 20, 2021 · 28d8571 · 28d8571
1 parent 3be41f6
commit 28d8571
Show file tree

Hide file tree

Showing 20 changed files with 116 additions and 3 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -63,7 +63,8 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
         with:
-          python-version: 3.8
+          # Mininum supported Python version
+          python-version: 3.6
       - name: Install dependencies
         run: python -m pip install tox
       - name: Build docs

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -14,7 +14,8 @@ formats:
   - epub
 
 python:
-  version: 3.8
+  # Mininum supported Python version
+  version: "3.6"
   install:
     - requirements: docs/requirements.txt
     - method: pip

diff --git a/docs/conf.py b/docs/conf.py
@@ -272,10 +272,31 @@
     "https://github.com/pypa/twine/issues/*",
     # Avoid errors from channels interpreted as anchors
     "https://web.libera.chat/#",
+    # Avoid error from InvalidPyPIUploadURL docstring
+    "https://upload.pypi.org/legacy",
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"https://docs.python.org/": None}
 
 # Be strict about the invalid references:
 nitpicky = True
+
+# TODO: Try to add these to intersphinx_mapping
+nitpick_ignore_regex = [
+    (r"py:.*", r"(pkginfo|requests|IO).*"),
+]
+
+# -- Options for apidoc output ------------------------------------------------
+
+autodoc_default_options = {
+    "members": True,
+    "private-members": True,
+    "undoc-members": True,
+    "member-order": "bysource",
+}
+
+autodoc_class_signature = "separated"
+autodoc_preserve_defaults = True
+# autodoc_typehints = "both"
+# autodoc_typehints_description_target = "documented"
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -211,6 +211,13 @@ specify either as a default, in the :file:`.pypirc` file, or pass on
 the command line), and the methods that upload the package securely to
 a URL.
 
+For more details, refer to the source documentation (currently a
+`work in progress <https://github.com/pypa/twine/issues/635>`_):
+
+.. toctree::
+
+   internal/twine
+
 Where Twine gets configuration and credentials
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/internal/twine.auth.rst b/docs/internal/twine.auth.rst
@@ -0,0 +1,4 @@
+twine.auth module
+=================
+
+.. automodule:: twine.auth
diff --git a/docs/internal/twine.cli.rst b/docs/internal/twine.cli.rst
@@ -0,0 +1,4 @@
+twine.cli module
+================
+
+.. automodule:: twine.cli
diff --git a/docs/internal/twine.commands.check.rst b/docs/internal/twine.commands.check.rst
@@ -0,0 +1,4 @@
+twine.commands.check module
+===========================
+
+.. automodule:: twine.commands.check
diff --git a/docs/internal/twine.commands.register.rst b/docs/internal/twine.commands.register.rst
@@ -0,0 +1,4 @@
+twine.commands.register module
+==============================
+
+.. automodule:: twine.commands.register
diff --git a/docs/internal/twine.commands.rst b/docs/internal/twine.commands.rst
@@ -0,0 +1,11 @@
+twine.commands package
+======================
+
+.. automodule:: twine.commands
+
+.. toctree::
+   :maxdepth: 4
+
+   twine.commands.check
+   twine.commands.register
+   twine.commands.upload
diff --git a/docs/internal/twine.commands.upload.rst b/docs/internal/twine.commands.upload.rst
@@ -0,0 +1,4 @@
+twine.commands.upload module
+============================
+
+.. automodule:: twine.commands.upload
diff --git a/docs/internal/twine.exceptions.rst b/docs/internal/twine.exceptions.rst
@@ -0,0 +1,4 @@
+twine.exceptions module
+=======================
+
+.. automodule:: twine.exceptions
diff --git a/docs/internal/twine.package.rst b/docs/internal/twine.package.rst
@@ -0,0 +1,4 @@
+twine.package module
+====================
+
+.. automodule:: twine.package
diff --git a/docs/internal/twine.repository.rst b/docs/internal/twine.repository.rst
@@ -0,0 +1,4 @@
+twine.repository module
+=======================
+
+.. automodule:: twine.repository
diff --git a/docs/internal/twine.rst b/docs/internal/twine.rst
@@ -0,0 +1,18 @@
+twine package
+=============
+
+.. automodule:: twine
+
+.. toctree::
+   :maxdepth: 4
+
+   twine.commands
+   twine.auth
+   twine.cli
+   twine.exceptions
+   twine.package
+   twine.repository
+   twine.settings
+   twine.utils
+   twine.wheel
+   twine.wininst
diff --git a/docs/internal/twine.settings.rst b/docs/internal/twine.settings.rst
@@ -0,0 +1,4 @@
+twine.settings module
+=====================
+
+.. automodule:: twine.settings
diff --git a/docs/internal/twine.utils.rst b/docs/internal/twine.utils.rst
@@ -0,0 +1,4 @@
+twine.utils module
+==================
+
+.. automodule:: twine.utils
diff --git a/docs/internal/twine.wheel.rst b/docs/internal/twine.wheel.rst
@@ -0,0 +1,4 @@
+twine.wheel module
+==================
+
+.. automodule:: twine.wheel
diff --git a/docs/internal/twine.wininst.rst b/docs/internal/twine.wininst.rst
@@ -0,0 +1,4 @@
+twine.wininst module
+====================
+
+.. automodule:: twine.wininst
diff --git a/tox.ini b/tox.ini
@@ -43,7 +43,8 @@ deps =
     -rdocs/requirements.txt
     sphinx-autobuild
 commands =
-    sphinx-autobuild -W -b html -d {envtmpdir}/doctrees \
+    sphinx-autobuild -b html -d {envtmpdir}/doctrees \
+        --watch twine \
         {posargs:--host 127.0.0.1} \
         docs docs/_build/html
 

diff --git a/twine/__init__.py b/twine/__init__.py
@@ -1,3 +1,8 @@
+"""Top-level module for Twine.
+
+The contents of this package are not a public API. For more details, see
+https://github.com/pypa/twine/issues/194 and https://github.com/pypa/twine/issues/665.
+"""
 # Copyright 2018 Donald Stufft and individual contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");