diff --git a/.bandit b/.bandit index 6e4e7d2..9a49af1 100644 --- a/.bandit +++ b/.bandit @@ -1,2 +1,2 @@ [bandit] -exclude: /tests +exclude: /tests, /docs diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 821cd25..5d0d4a0 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -75,3 +75,61 @@ jobs: with: name: fido2-python-sdist path: dist + + docs: + runs-on: ubuntu-latest + name: Build sphinx documentation + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.10 + + - name: Install python dependencies + run: | + python -m pip install --upgrade pip + python -m pip install poetry + poetry install -E pcsc + + - name: Build sphinx documentation + run: poetry run make -C docs/ html + + - name: Upload documentation + uses: actions/upload-artifact@v4 + with: + name: python-fido2-docs + path: docs/_build/html + + docs_win: + runs-on: windows-latest + name: Build sphinx documentation on Windows + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.10 + + - name: Install python dependencies + shell: bash + run: | + python -m pip install --upgrade pip + python -m pip install poetry + poetry install -E pcsc + + - name: Build sphinx documentation + shell: bash + run: poetry run make -C docs/ html + + - name: Upload documentation + uses: actions/upload-artifact@v4 + with: + name: python-fido2-docs-win + path: docs/_build/html + + diff --git a/.gitignore b/.gitignore index d292caf..d381c4b 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ dist/ ChangeLog man/*.1 poetry.lock +**/_build # Unit test / coverage reports htmlcov/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2f19262..8e7f035 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,9 +11,10 @@ repos: rev: 1.7.10 hooks: - id: bandit - exclude: ^tests/ + exclude: ^(tests/|docs/) - repo: https://github.com/pre-commit/mirrors-mypy rev: v1.13.0 hooks: - id: mypy + exclude: ^docs/ files: ^fido2/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +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 + +# 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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..6fb6903 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,193 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +import re + +sys.path.insert(0, os.path.abspath("../")) + + +def get_version(): + with open("../fido2/__init__.py", "r") as f: + match = re.search(r"(?m)^__version__\s*=\s*['\"](.+)['\"]$", f.read()) + return match.group(1) + + +# -- Project information ----------------------------------------------------- + +project = "python-fido2" +copyright = "2024, Yubico" +author = "Yubico" + +# The full version, including alpha/beta/rc tags +release = get_version() + +# The short X.Y version +version = ".".join(release.split(".")[:2]) + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx_autodoc_typehints", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" + +# The master toctree document. +master_doc = "index" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + + +# -- 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 = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +html_favicon = "favicon.ico" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +# Don't show a "View page source" link on each page. +html_show_sourcelink = False + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "python-fido2doc" + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, + "python-fido2.tex", + "python-fido2 Documentation", + "Yubico", + "manual", + ) +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "python-fido2", "python-fido2 Documentation", [author], 1)] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "python-fido2", + "python-fido2 Documentation", + author, + "python-fido2", + "One line description of project.", + "Miscellaneous", + ) +] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + "python": ("https://docs.python.org/", None), + "cryptography": ("https://cryptography.io/en/latest/", None), +} + + +# Custom config +autodoc_member_order = "bysource" diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..c7194cc Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..c14c80b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,21 @@ +.. python-fido2 documentation master file, created by + sphinx-quickstart on Fri Nov 8 11:41:52 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to python-fido2's documentation! +======================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + rst/packages + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/rst/fido2.attestation.rst b/docs/rst/fido2.attestation.rst new file mode 100644 index 0000000..1027362 --- /dev/null +++ b/docs/rst/fido2.attestation.rst @@ -0,0 +1,61 @@ +fido2.attestation package +========================= + +Submodules +---------- + +fido2.attestation.android module +-------------------------------- + +.. automodule:: fido2.attestation.android + :members: + :undoc-members: + :show-inheritance: + +fido2.attestation.apple module +------------------------------ + +.. automodule:: fido2.attestation.apple + :members: + :undoc-members: + :show-inheritance: + +fido2.attestation.base module +----------------------------- + +.. automodule:: fido2.attestation.base + :members: + :undoc-members: + :show-inheritance: + +fido2.attestation.packed module +------------------------------- + +.. automodule:: fido2.attestation.packed + :members: + :undoc-members: + :show-inheritance: + +fido2.attestation.tpm module +---------------------------- + +.. automodule:: fido2.attestation.tpm + :members: + :undoc-members: + :show-inheritance: + +fido2.attestation.u2f module +---------------------------- + +.. automodule:: fido2.attestation.u2f + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: fido2.attestation + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/rst/fido2.ctap2.rst b/docs/rst/fido2.ctap2.rst new file mode 100644 index 0000000..cabc827 --- /dev/null +++ b/docs/rst/fido2.ctap2.rst @@ -0,0 +1,69 @@ +fido2.ctap2 package +=================== + +Submodules +---------- + +fido2.ctap2.base module +----------------------- + +.. automodule:: fido2.ctap2.base + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap2.bio module +---------------------- + +.. automodule:: fido2.ctap2.bio + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap2.blob module +----------------------- + +.. automodule:: fido2.ctap2.blob + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap2.config module +------------------------- + +.. automodule:: fido2.ctap2.config + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap2.credman module +-------------------------- + +.. automodule:: fido2.ctap2.credman + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap2.extensions module +----------------------------- + +.. automodule:: fido2.ctap2.extensions + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap2.pin module +---------------------- + +.. automodule:: fido2.ctap2.pin + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: fido2.ctap2 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/rst/fido2.hid.rst b/docs/rst/fido2.hid.rst new file mode 100644 index 0000000..92b73fe --- /dev/null +++ b/docs/rst/fido2.hid.rst @@ -0,0 +1,69 @@ +fido2.hid package +================= + +Submodules +---------- + +fido2.hid.base module +--------------------- + +.. automodule:: fido2.hid.base + :members: + :undoc-members: + :show-inheritance: + +fido2.hid.freebsd module +------------------------ + +.. automodule:: fido2.hid.freebsd + :members: + :undoc-members: + :show-inheritance: + +fido2.hid.linux module +---------------------- + +.. automodule:: fido2.hid.linux + :members: + :undoc-members: + :show-inheritance: + +fido2.hid.macos module +---------------------- + +.. automodule:: fido2.hid.macos + :members: + :undoc-members: + :show-inheritance: + +fido2.hid.netbsd module +----------------------- + +.. automodule:: fido2.hid.netbsd + :members: + :undoc-members: + :show-inheritance: + +fido2.hid.openbsd module +------------------------ + +.. automodule:: fido2.hid.openbsd + :members: + :undoc-members: + :show-inheritance: + +fido2.hid.windows module +------------------------ + +.. automodule:: fido2.hid.windows + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: fido2.hid + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/rst/fido2.rst b/docs/rst/fido2.rst new file mode 100644 index 0000000..337d7b7 --- /dev/null +++ b/docs/rst/fido2.rst @@ -0,0 +1,127 @@ +fido2 package +============= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + fido2.attestation + fido2.ctap2 + fido2.hid + +Submodules +---------- + +fido2.cbor module +----------------- + +.. automodule:: fido2.cbor + :members: + :undoc-members: + :show-inheritance: + +fido2.client module +------------------- + +.. automodule:: fido2.client + :members: + :undoc-members: + :show-inheritance: + +fido2.cose module +----------------- + +.. automodule:: fido2.cose + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap module +----------------- + +.. automodule:: fido2.ctap + :members: + :undoc-members: + :show-inheritance: + +fido2.ctap1 module +------------------ + +.. automodule:: fido2.ctap1 + :members: + :undoc-members: + :show-inheritance: + +fido2.features module +--------------------- + +.. automodule:: fido2.features + :members: + :undoc-members: + :show-inheritance: + +fido2.mds3 module +----------------- + +.. automodule:: fido2.mds3 + :members: + :undoc-members: + :show-inheritance: + +fido2.pcsc module +----------------- + +.. automodule:: fido2.pcsc + :members: + :undoc-members: + :show-inheritance: + +fido2.rpid module +----------------- + +.. automodule:: fido2.rpid + :members: + :undoc-members: + :show-inheritance: + +fido2.server module +------------------- + +.. automodule:: fido2.server + :members: + :undoc-members: + :show-inheritance: + +fido2.utils module +------------------ + +.. automodule:: fido2.utils + :members: + :undoc-members: + :show-inheritance: + +fido2.webauthn module +--------------------- + +.. automodule:: fido2.webauthn + :members: + :undoc-members: + :show-inheritance: + +fido2.win\_api module +--------------------- + +.. automodule:: fido2.win_api + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: fido2 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/rst/packages.rst b/docs/rst/packages.rst new file mode 100644 index 0000000..3fe3549 --- /dev/null +++ b/docs/rst/packages.rst @@ -0,0 +1,7 @@ +python-fido2 +============ + +.. toctree:: + :maxdepth: 4 + + fido2 diff --git a/fido2/server.py b/fido2/server.py index bd30f16..bbaa935 100644 --- a/fido2/server.py +++ b/fido2/server.py @@ -471,6 +471,7 @@ class U2FFido2Server(Fido2Server): :param app_id: The appId which was used for U2F registration. :param verify_u2f_origin: (optional) Alternative function to validate an origin for U2F credentials. + For other parameters, see Fido2Server. """ diff --git a/pyproject.toml b/pyproject.toml index 81401b4..d9700c3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,6 +40,9 @@ pcsc = ["pyscard"] [tool.poetry.dev-dependencies] pytest = "^7.0" +Sphinx = {version = "^8.1", python = ">=3.10"} +sphinx-rtd-theme = {version = "^3.0.1", python = ">=3.10"} +sphinx-autodoc-typehints = {version = "^2.5.0", python = ">=3.10"} [build-system] requires = ["poetry-core>=1.0.0"]