From bafc5b1b4ca9d0fc9aac901b96705c43cb677ab6 Mon Sep 17 00:00:00 2001 From: prateek-dagar Date: Fri, 7 Aug 2026 12:34:27 +0530 Subject: [PATCH] docs: generate and publish API documentation with Sphinx and MyST-Parser --- .github/workflows/ci.yml | 13 ++++++++++ .readthedocs.yaml | 21 ++++++++++++++++ docs/_static/.gitkeep | 1 + docs/conf.py | 8 +++++- docs/index.rst | 12 +++------ docs/requirements.txt | 6 +++-- docs/source/langcodes.rst | 51 ++------------------------------------- docs/source/modules.rst | 7 ------ tox.ini | 12 ++++++++- 9 files changed, 63 insertions(+), 68 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/_static/.gitkeep delete mode 100644 docs/source/modules.rst diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 166547ad..ec58249d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,3 +25,16 @@ jobs: name: junit-${{ matrix.python-version }} path: junit/* + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: Install tox + run: pip install tox + - name: Build documentation + run: tox -e docs + diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..4205a005 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,21 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + +python: + install: + - method: pip + path: . + extra_requirements: + - data + - requirements: docs/requirements.txt diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..c27d459c --- /dev/null +++ b/docs/_static/.gitkeep @@ -0,0 +1 @@ +# Keep docs/_static tracked by git diff --git a/docs/conf.py b/docs/conf.py index b198b773..7f68c3d2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,6 +31,7 @@ 'sphinx.ext.autodoc', # https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx 'myst_parser', + 'sphinx_copybutton', ] # Add any paths that contain templates here, relative to this directory. @@ -47,7 +48,12 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'sphinx_book_theme' + +html_theme_options = { + "show_navbar_depth": 2, + "show_toc_level": 2, +} # 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, diff --git a/docs/index.rst b/docs/index.rst index 334edfcb..27b3e430 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,16 +1,12 @@ -.. langcodes documentation master file, created by - sphinx-quickstart on Fri Apr 16 21:32:52 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to langcodes's documentation! -===================================== +.. include:: ../README.md + :parser: myst_parser.sphinx_ .. toctree:: :maxdepth: 2 :caption: Contents: - source/modules + self + source/langcodes Indices and tables diff --git a/docs/requirements.txt b/docs/requirements.txt index 37a30b2f..2c7d8dac 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,4 @@ -myst_parser - +sphinx +sphinx-book-theme +myst-parser +sphinx-copybutton diff --git a/docs/source/langcodes.rst b/docs/source/langcodes.rst index ef29e118..e5778988 100644 --- a/docs/source/langcodes.rst +++ b/docs/source/langcodes.rst @@ -1,25 +1,9 @@ -langcodes package +Langcodes package ================= Submodules ---------- -langcodes.build\_data module ----------------------------- - -.. automodule:: langcodes.build_data - :members: - :undoc-members: - :show-inheritance: - -langcodes.data\_dicts module ----------------------------- - -.. automodule:: langcodes.data_dicts - :members: - :undoc-members: - :show-inheritance: - langcodes.language\_distance module ----------------------------------- @@ -28,38 +12,6 @@ langcodes.language\_distance module :undoc-members: :show-inheritance: -langcodes.language\_lists module --------------------------------- - -.. automodule:: langcodes.language_lists - :members: - :undoc-members: - :show-inheritance: - -langcodes.registry\_parser module ---------------------------------- - -.. automodule:: langcodes.registry_parser - :members: - :undoc-members: - :show-inheritance: - -langcodes.tag\_parser module ----------------------------- - -.. automodule:: langcodes.tag_parser - :members: - :undoc-members: - :show-inheritance: - -langcodes.util module ---------------------- - -.. automodule:: langcodes.util - :members: - :undoc-members: - :show-inheritance: - Module contents --------------- @@ -67,3 +19,4 @@ Module contents :members: :undoc-members: :show-inheritance: + :exclude-members: ATTRIBUTES, BROADER_KEYSETS, MATCHABLE_KEYSETS diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index 26c9a30d..00000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -langcodes -========= - -.. toctree:: - :maxdepth: 4 - - langcodes diff --git a/tox.ini b/tox.ini index 195a4803..dd4cefa9 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = py36, py37, py38, py39, py310, py311, py312 +envlist = py36, py37, py38, py39, py310, py311, py312, p313 skipsdist = True [testenv] @@ -9,3 +9,13 @@ deps = language_data commands = pip install . pytest + +[testenv:docs] +deps = + sphinx + sphinx-book-theme + myst-parser + sphinx-copybutton + language_data +commands = + sphinx-build -aEWnb html docs docs/build/html