docs: Publish docs (#23)

.flake8

@@ -1,4 +1,7 @@
 [flake8]
+ignore =
+    ; Parameter type mismatch
+    DAR103
 select = DAR
 docstring_style=google
 max-line-length = 88

.github/workflows/documentation-links.yaml

@@ -0,0 +1,16 @@
+name: readthedocs/actions
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "pep610"

.github/workflows/test.yaml

@@ -100,7 +100,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
-        id: setup-python
         with:
           cache: pip
           python-version: ${{ matrix.python-version }}
@@ -109,10 +108,12 @@ jobs:
         env:
           PIP_CONSTRAINT: .github/workflows/constraints.txt
         run: |
-          pipx install --python=${{ steps.setup-python.outputs.python-path }} hatch
+          pipx install hatch
       - name: Run tests
+        env:
+          HATCH_ENV: all
         run: |
-          hatch run cov
+          hatch run +py=${{ matrix.python-version }} cov
       - uses: actions/upload-artifact@v4
         with:
           name: coverage-data-${{ matrix.os }}-${{ matrix.python-version }}

.readthedocs.yaml

@@ -0,0 +1,25 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow || true
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -3,6 +3,7 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/pep610.svg)](https://pypi.org/project/pep610)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pep610.svg)](https://pypi.org/project/pep610)
 [![codecov](https://codecov.io/gh/edgarrmondragon/pep610/graph/badge.svg?token=6W1M6P9LYI)](https://codecov.io/gh/edgarrmondragon/pep610)
+[![Documentation Status](https://readthedocs.org/projects/pep610/badge/?version=latest)](https://pep610.readthedocs.io/en/latest/?badge=latest)
 
 [PEP 610][pep610] specifies how the Direct URL Origin of installed distributions should be recorded.
 

docs/conf.py

@@ -0,0 +1,74 @@
+"""Sphinx configuration."""
+
+from __future__ import annotations
+
+import pep610
+
+# Add any Sphinx extension module names here, as strings.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx_design",
+]
+
+# General information about the project.
+project = "pep610"
+author = "Edgar Ramírez-Mondragón"
+version = pep610.__version__
+release = pep610.__version__
+project_copyright = f"2023, {author}"
+
+# -- Options for HTML output --------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+html_theme = "furo"
+html_title = "PEP 610 - Direct URL Parser and Builder for Python"
+html_theme_options = {
+    "navigation_with_keys": True,
+    "source_repository": "https://github.com/edgarrmondragon/citric/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+
+# -- Options for autodoc ----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+autodoc_member_order = "bysource"
+autodoc_preserve_defaults = True
+
+# Automatically extract typehints when specified and place them in
+# descriptions of the relevant function/method.
+autodoc_typehints = "description"
+
+# Only document types for parameters or return values that are already documented by the
+# docstring.
+autodoc_typehints_description_target = "documented"
+
+# -- Options for extlinks -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
+
+extlinks_detect_hardcoded_links = True
+extlinks = {
+    "spec": (
+        "https://packaging.python.org/en/latest/specifications/direct-url-data-structure/#%s-urls",
+        "specification for %s URLs",
+    ),
+}
+
+# -- Options for intersphinx ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+intersphinx_mapping = {
+    "metadata": ("https://importlib-metadata.readthedocs.io/en/latest", None),
+    "python": ("https://docs.python.org/3/", None),
+}
+
+# -- Options for Myst Parser -------------------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/configuration.html
+myst_enable_extensions = ["colon_fence"]

docs/index.md

@@ -0,0 +1,83 @@
+# PEP 610 Parser and Builder
+
+*A parser and builder for [PEP 610 direct URL metadata](https://packaging.python.org/en/latest/specifications/direct-url-data-structure).*
+
+Release **v{sub-ref}`version`**.
+
+::::{tab-set}
+
+:::{tab-item} Python 3.10+
+
+```python
+from importlib import metadata
+
+import pep610
+
+dist = metadata.distribution("pep610")
+data = pep610.read_from_distribution(dist)
+
+match data:
+    case pep610.DirData(url, pep610.DirInfo(editable=True)):
+        print("Editable install")
+    case _:
+        print("Not editable install")
+```
+
+:::
+
+:::{tab-item} Python 3.9+
+```python
+from importlib import metadata
+
+import pep610
+
+dist = metadata.distribution("pep610")
+data = pep610.read_from_distribution(dist)
+
+if isinstance(data, pep610.DirData) and data.dir_info.is_editable():
+    print("Editable install")
+else:
+    print("Not editable install")
+```
+:::
+::::
+
+## Supported formats
+
+```{eval-rst}
+.. autoclass:: pep610.ArchiveData
+    :members:
+```
+
+```{eval-rst}
+.. autoclass:: pep610.DirData
+    :members:
+```
+
+```{eval-rst}
+.. autoclass:: pep610.VCSData
+    :members:
+```
+
+## Other classes
+
+```{eval-rst}
+.. autoclass:: pep610.ArchiveInfo
+    :members:
+```
+
+```{eval-rst}
+.. autoclass:: pep610.DirInfo
+    :members:
+```
+
+```{eval-rst}
+.. autoclass:: pep610.VCSInfo
+    :members:
+```
+
+## Functions
+
+```{eval-rst}
+.. autofunction:: pep610.read_from_distribution
+```

pyproject.toml

@@ -42,6 +42,12 @@ optional-dependencies.dev = [
   "hypothesis-jsonschema",
   "pytest",
 ]
+optional-dependencies.docs = [
+  "furo==2023.9.10",
+  "myst-parser==2",
+  "sphinx==7.2.6",
+  "sphinx_design==0.5",
+]
 urls.Documentation = "https://github.com/unknown/pep610#readme"
 urls.Issues = "https://github.com/unknown/pep610/issues"
 urls.Source = "https://github.com/unknown/pep610"
@@ -92,6 +98,11 @@ style = [
 fmt = ["ruff check --fix {args:.}", "ruff format {args:.}", "style"]
 all = ["style", "typing"]
 
+[tool.hatch.envs.docs]
+features = ["docs"]
+[tool.hatch.envs.docs.scripts]
+build = "sphinx-build -W -b html docs docs/_build"
+
 [tool.ruff]
 line-length = 100
 preview = true
@@ -168,11 +179,14 @@ ban-relative-imports = "all"
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*" = [
   "PLR2004", # magic-value-comparison
-  "S101", # assert
-  "TID252", # relative-imports
-  "D100", # undocumented-public-module
-  "D104",	# undocumented-public-package
-  "ANN201", # missing-return-type-undocumented-public-function
+  "S101",    # assert
+  "TID252",  # relative-imports
+  "D100",    # undocumented-public-module
+  "D104",	   # undocumented-public-package
+  "ANN201",  # missing-return-type-undocumented-public-function
+]
+"docs/conf.py" = [
+  "INP001", # Not an implicit namespace packages
 ]
 
 [tool.ruff.lint.pydocstyle]