Merge pull request #129 from trailofbits/ww/ci-doc-builds

di · web-flow · commit 3b06ff6cd6ff · 2021-11-22T09:58:26.000-05:00
github/workflows: add a docs workflow
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,38 @@
+name: docs-deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+
+      - name: deps
+        run: make dev
+
+      - name: docs
+        run: |
+          make doc
+          mv ./html/pip_audit /tmp/pip_audit
+
+      - name: deploy
+        run: |
+          # Configure git, checkout a new orphan branch for the docs.
+          git config --global user.name 'github.actions'
+          git config --global user.email 'github-actions@github.com'
+          git checkout --orphan gh-pages
+
+          # Clear out all repo state, copy in the docs built in the previous step.
+          git rm -rf . && git clean -fd
+          mv /tmp/pip_audit ./docs
+
+          # Check in the docs, push.
+          git add --all .
+          git commit -m "[docs] deploy: ${GITHUB_SHA}"
+          git push --force origin gh-pages
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -107,11 +107,15 @@ pytest --cov=pip_audit test/
 python -m coverage report -m --fail-under 100
 ```
 
-### Documentation builds
+### Documentation
 
 `pip-audit` uses [`pdoc3`](https://github.com/pdoc3/pdoc) to generate HTML documentation for
 the public Python APIs.
 
+Live documentation for the `main` branch is hosted
+[here](https://trailofbits.github.io/pip-audit/). Only the public APIs are
+documented, all undocumented APIs are **intentionally private and unstable.**
+
 If you're running Python 3.7 or newer, you can run the documentation build locally:
 
 ```bash
diff --git a/pip_audit/__init__.py b/pip_audit/__init__.py
@@ -1,7 +1,5 @@
 """
-The `pip_audit` package.
-
-The `pip_audit` APIs are documented in each submodule.
+The `pip_audit` APIs.
 """
 
 from pip_audit._version import __version__  # noqa: F401
diff --git a/pip_audit/_audit.py b/pip_audit/_audit.py
@@ -6,8 +6,8 @@
 from dataclasses import dataclass
 from typing import Iterator, List, Tuple
 
-from pip_audit.dependency_source import DependencySource
-from pip_audit.service import Dependency, VulnerabilityResult, VulnerabilityService
+from pip_audit._dependency_source import DependencySource
+from pip_audit._service import Dependency, VulnerabilityResult, VulnerabilityService
 
 logger = logging.getLogger(__name__)
 
diff --git a/pip_audit/_cli.py b/pip_audit/_cli.py
@@ -12,17 +12,17 @@
 from typing import List, Optional
 
 from pip_audit import __version__
-from pip_audit.audit import AuditOptions, Auditor
-from pip_audit.dependency_source import (
+from pip_audit._audit import AuditOptions, Auditor
+from pip_audit._dependency_source import (
     DependencySource,
     PipSource,
     RequirementSource,
     ResolveLibResolver,
 )
-from pip_audit.format import ColumnsFormat, CycloneDxFormat, JsonFormat, VulnerabilityFormat
-from pip_audit.service import OsvService, PyPIService, VulnerabilityService
-from pip_audit.state import AuditSpinner
-from pip_audit.util import assert_never
+from pip_audit._format import ColumnsFormat, CycloneDxFormat, JsonFormat, VulnerabilityFormat
+from pip_audit._service import OsvService, PyPIService, VulnerabilityService
+from pip_audit._state import AuditSpinner
+from pip_audit._util import assert_never
 
 logger = logging.getLogger(__name__)
 logging.basicConfig(level=os.environ.get("PIP_AUDIT_LOGLEVEL", "INFO").upper())
diff --git a/pip_audit/_dependency_source/__init__.py b/pip_audit/_dependency_source/__init__.py
diff --git a/pip_audit/_dependency_source/interface.py b/pip_audit/_dependency_source/interface.py
@@ -8,7 +8,7 @@
 
 from packaging.requirements import Requirement
 
-from pip_audit.service import Dependency
+from pip_audit._service import Dependency
 
 
 class DependencySource(ABC):
diff --git a/pip_audit/_dependency_source/pip.py b/pip_audit/_dependency_source/pip.py
@@ -9,9 +9,9 @@
 import pip_api
 from packaging.version import Version
 
-from pip_audit.dependency_source import DependencySource, DependencySourceError
-from pip_audit.service import Dependency
-from pip_audit.state import AuditState
+from pip_audit._dependency_source import DependencySource, DependencySourceError
+from pip_audit._service import Dependency
+from pip_audit._state import AuditState
 
 logger = logging.getLogger(__name__)
 
diff --git a/pip_audit/_dependency_source/requirement.py b/pip_audit/_dependency_source/requirement.py
@@ -9,14 +9,14 @@
 from pip_api import parse_requirements
 from pip_api.exceptions import PipError
 
-from pip_audit.dependency_source import (
+from pip_audit._dependency_source import (
     DependencyResolver,
     DependencyResolverError,
     DependencySource,
     DependencySourceError,
 )
-from pip_audit.service import Dependency
-from pip_audit.state import AuditState
+from pip_audit._service import Dependency
+from pip_audit._state import AuditState
 
 
 class RequirementSource(DependencySource):
diff --git a/pip_audit/_dependency_source/resolvelib/__init__.py b/pip_audit/_dependency_source/resolvelib/__init__.py
diff --git a/pip_audit/_dependency_source/resolvelib/pypi_provider.py b/pip_audit/_dependency_source/resolvelib/pypi_provider.py
@@ -25,8 +25,8 @@
 from packaging.version import Version
 from resolvelib.providers import AbstractProvider
 
-from pip_audit.state import AuditState
-from pip_audit.virtual_env import VirtualEnv
+from pip_audit._state import AuditState
+from pip_audit._virtual_env import VirtualEnv
 
 PYTHON_VERSION = Version(python_version())
 
diff --git a/pip_audit/_dependency_source/resolvelib/resolvelib.py b/pip_audit/_dependency_source/resolvelib/resolvelib.py
@@ -9,9 +9,9 @@
 from requests.exceptions import HTTPError
 from resolvelib import BaseReporter, Resolver
 
-from pip_audit.dependency_source import DependencyResolver, DependencyResolverError
-from pip_audit.service.interface import Dependency
-from pip_audit.state import AuditState
+from pip_audit._dependency_source import DependencyResolver, DependencyResolverError
+from pip_audit._service.interface import Dependency
+from pip_audit._state import AuditState
 
 from .pypi_provider import PyPIProvider
 
diff --git a/pip_audit/_format/__init__.py b/pip_audit/_format/__init__.py
diff --git a/pip_audit/_format/columns.py b/pip_audit/_format/columns.py
@@ -7,7 +7,7 @@
 
 from packaging.version import Version
 
-import pip_audit.service as service
+import pip_audit._service as service
 
 from .interface import VulnerabilityFormat
 
diff --git a/pip_audit/_format/cyclonedx.py b/pip_audit/_format/cyclonedx.py
@@ -11,7 +11,7 @@
 from cyclonedx.model.vulnerability import Vulnerability
 from cyclonedx.parser import BaseParser
 
-import pip_audit.service as service
+import pip_audit._service as service
 
 from .interface import VulnerabilityFormat
 
diff --git a/pip_audit/_format/interface.py b/pip_audit/_format/interface.py
@@ -4,7 +4,7 @@
 from abc import ABC
 from typing import Dict, List
 
-import pip_audit.service as service
+import pip_audit._service as service
 
 
 class VulnerabilityFormat(ABC):
diff --git a/pip_audit/_format/json.py b/pip_audit/_format/json.py
@@ -5,7 +5,7 @@
 import json
 from typing import Any, Dict, List
 
-import pip_audit.service as service
+import pip_audit._service as service
 
 from .interface import VulnerabilityFormat
 
diff --git a/pip_audit/_service/__init__.py b/pip_audit/_service/__init__.py
diff --git a/pip_audit/_service/interface.py b/pip_audit/_service/interface.py
diff --git a/pip_audit/_service/osv.py b/pip_audit/_service/osv.py
diff --git a/pip_audit/_service/pypi.py b/pip_audit/_service/pypi.py
diff --git a/pip_audit/_state.py b/pip_audit/_state.py
diff --git a/pip_audit/_util.py b/pip_audit/_util.py
diff --git a/pip_audit/_virtual_env.py b/pip_audit/_virtual_env.py
@@ -9,7 +9,7 @@
 
 from packaging.version import Version
 
-from .state import AuditState
+from ._state import AuditState
 
 
 class VirtualEnv(venv.EnvBuilder):
diff --git a/pyproject.toml b/pyproject.toml
@@ -9,11 +9,11 @@ line-length = 100
 
 [tool.coverage.run]
 # don't attempt code coverage for the CLI entrypoints
-omit = ["pip_audit/cli.py"]
+omit = ["pip_audit/_cli.py"]
 
 [tool.interrogate]
 # don't enforce documentation coverage for packaging, testing, the virtual
 # environment, or the CLI (which is documented separately).
-exclude = ["setup.py", "env", "test", "pip_audit/cli.py", "pip_audit/_version.py"]
+exclude = ["setup.py", "env", "test", "pip_audit/_cli.py", "pip_audit/_version.py"]
 ignore-semiprivate = true
 fail-under = 100
diff --git a/setup.py b/setup.py
@@ -22,7 +22,7 @@
     packages=find_packages(),
     entry_points={
         "console_scripts": [
-            "pip-audit = pip_audit.cli:audit",
+            "pip-audit = pip_audit._cli:audit",
         ]
     },
     platforms="any",
diff --git a/test/conftest.py b/test/conftest.py
@@ -1,8 +1,8 @@
 import pytest
 from packaging.version import Version
 
-from pip_audit.dependency_source.interface import DependencySource
-from pip_audit.service.interface import Dependency, VulnerabilityResult, VulnerabilityService
+from pip_audit._dependency_source.interface import DependencySource
+from pip_audit._service.interface import Dependency, VulnerabilityResult, VulnerabilityService
 
 
 @pytest.fixture(autouse=True)
diff --git a/test/dependency_source/test_interface.py b/test/dependency_source/test_interface.py
@@ -1,4 +1,4 @@
-from pip_audit.service.interface import Dependency
+from pip_audit._service.interface import Dependency
 
 
 def test_dependency_source(dep_source):
diff --git a/test/dependency_source/test_pip.py b/test/dependency_source/test_pip.py
@@ -4,8 +4,8 @@
 from packaging.version import Version
 
 import pip_audit
-from pip_audit.dependency_source import pip
-from pip_audit.service.interface import Dependency
+from pip_audit._dependency_source import pip
+from pip_audit._service.interface import Dependency
 
 
 def test_pip_source():
diff --git a/test/dependency_source/test_requirement.py b/test/dependency_source/test_requirement.py
@@ -6,14 +6,14 @@
 from packaging.version import Version
 from pip_api import _parse_requirements
 
-from pip_audit.dependency_source import (
+from pip_audit._dependency_source import (
     DependencyResolver,
     DependencyResolverError,
     DependencySourceError,
     ResolveLibResolver,
     requirement,
 )
-from pip_audit.service import Dependency
+from pip_audit._service import Dependency
 
 
 def test_requirement_source(monkeypatch):
diff --git a/test/dependency_source/test_resolvelib.py b/test/dependency_source/test_resolvelib.py
@@ -8,9 +8,9 @@
 from requests.exceptions import HTTPError
 from resolvelib.resolvers import InconsistentCandidate, ResolutionImpossible
 
-from pip_audit.dependency_source import resolvelib
-from pip_audit.dependency_source.resolvelib import pypi_provider
-from pip_audit.service.interface import Dependency
+from pip_audit._dependency_source import resolvelib
+from pip_audit._dependency_source.resolvelib import pypi_provider
+from pip_audit._service.interface import Dependency
 
 
 def get_package_mock(data):
diff --git a/test/format/conftest.py b/test/format/conftest.py
@@ -3,7 +3,7 @@
 import pytest
 from packaging.version import Version
 
-import pip_audit.service as service
+import pip_audit._service as service
 
 _TEST_VULN_DATA: Dict[service.Dependency, List[service.VulnerabilityResult]] = {
     service.Dependency(name="foo", version="1.0"): [
diff --git a/test/format/test_columns.py b/test/format/test_columns.py
@@ -1,4 +1,4 @@
-import pip_audit.format as format
+import pip_audit._format as format
 
 
 def test_columns(vuln_data):
diff --git a/test/format/test_cyclonedx.py b/test/format/test_cyclonedx.py
@@ -1,7 +1,7 @@
 import json
 import xml.etree.ElementTree as ET
 
-from pip_audit.format import CycloneDxFormat
+from pip_audit._format import CycloneDxFormat
 
 
 def test_cyclonedx_inner_json(vuln_data):
diff --git a/test/format/test_json.py b/test/format/test_json.py
@@ -1,6 +1,6 @@
 import json
 
-import pip_audit.format as format
+import pip_audit._format as format
 
 
 def test_json(vuln_data):
diff --git a/test/service/conftest.py b/test/service/conftest.py
@@ -0,0 +1,10 @@
+import tempfile
+
+import pytest
+
+
+@pytest.fixture(scope="session")
+def cache_dir():
+    cache = tempfile.TemporaryDirectory()
+    yield cache.name
+    cache.cleanup()
diff --git a/test/service/test_osv.py b/test/service/test_osv.py
@@ -5,7 +5,7 @@
 from packaging.version import Version
 from requests.exceptions import HTTPError
 
-import pip_audit.service as service
+import pip_audit._service as service
 
 
 class OsvServiceTest(unittest.TestCase):
@@ -74,7 +74,7 @@ def raise_for_status(self):
 
         return MockResponse()
 
-    @mock.patch("pip_audit.service.osv.requests.post", side_effect=get_error_response)
+    @mock.patch("pip_audit._service.osv.requests.post", side_effect=get_error_response)
     def test_osv_error_response(self, mock_post):
         osv = service.OsvService()
         dep = service.Dependency("jinja2", Version("2.4.1"))
diff --git a/test/service/test_pypi.py b/test/service/test_pypi.py
diff --git a/test/test_audit.py b/test/test_audit.py
diff --git a/test/test_virtual_env.py b/test/test_virtual_env.py

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@`
`22`	`22`	`packages=find_packages(),`
`23`	`23`	`entry_points={`
`24`	`24`	`"console_scripts": [`
`25`		`- "pip-audit = pip_audit.cli:audit",`
	`25`	`+ "pip-audit = pip_audit._cli:audit",`
`26`	`26`	`]`
`27`	`27`	`},`
`28`	`28`	`platforms="any",`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-from pip_audit.service.interface import Dependency`
	`1`	`+from pip_audit._service.interface import Dependency`
`2`	`2`
`3`	`3`
`4`	`4`	`def test_dependency_source(dep_source):`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import pip_audit.format as format`
	`1`	`+import pip_audit._format as format`
`2`	`2`
`3`	`3`
`4`	`4`	`def test_columns(vuln_data):`