diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index eb5b82f..cc14a9e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -39,7 +39,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install sphinx sphinx-autodoc-typehints + pip install sphinx sphinx-autodoc-typehints sphinx_rtd_theme pip install -e . - name: Build documentation diff --git a/.readthedocs.yml b/.readthedocs.yml index 21b0814..0f125df 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -4,6 +4,12 @@ # Required version: 2 +# Set the OS, Python version, and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.10" + # Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py @@ -17,7 +23,7 @@ formats: - pdf python: - version: 3.8 install: - requirements: docs/requirements.txt - - {path: ., method: pip} + - method: pip + path: . diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3d98598..503206e 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -232,6 +232,56 @@ on PyPI_, the following steps can be used to release a new version for uploaded to PyPI_ correctly. +Deploying Documentation to ReadTheDocs +-------------------------------------- + +This project is configured to work with `Read the Docs`_ for automatic +documentation hosting. To deploy the documentation to ReadTheDocs.io, follow +these steps: + +#. **Create a Read the Docs account**: Go to `readthedocs.org`_ and create an + account (you can sign up using your GitHub account). + +#. **Import your project**: After logging in, click on "Import a Project" and + select the ``XAI-Lib`` repository from your GitHub account. If you don't see + it, you may need to refresh your repository list or manually enter the + repository URL. + +#. **Configure the project**: Read the Docs will automatically detect the + ``.readthedocs.yml`` configuration file in the repository root. The + configuration specifies: + + - Python version: 3.10 + - Documentation builder: Sphinx + - Configuration file location: ``docs/conf.py`` + - Additional formats: PDF + +#. **Build the documentation**: Once imported, Read the Docs will automatically + build the documentation. You can trigger manual builds from the project + dashboard. + +#. **Enable automatic builds**: By default, Read the Docs will build the + documentation on every push to the main branch. You can also configure + webhook integration for pull request previews. + +#. **Access your documentation**: After a successful build, your documentation + will be available at ``https://xai-lib.readthedocs.io/`` (or a similar URL + based on your project name). + +Additional configuration options include: + +- **Versioning**: Read the Docs can build documentation for multiple versions + (branches/tags) of your project. +- **Custom domains**: You can configure a custom domain for your documentation. +- **Notifications**: Set up build notifications for failures. + +For more information, see the `Read the Docs documentation`_. + +.. _Read the Docs: https://readthedocs.org/ +.. _readthedocs.org: https://readthedocs.org/ +.. _Read the Docs documentation: https://docs.readthedocs.io/en/stable/ + + .. [#contrib1] Even though, these resources focus on open source projects and communities, the general ideas behind collaborating with other developers diff --git a/docs/conf.py b/docs/conf.py index c0cf6f9..0ae20d0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -153,14 +153,14 @@ # 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_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 = { - "sidebar_width": "300px", - "page_width": "1200px" + "navigation_depth": 4, + "collapse_navigation": False, } # Add any paths that contain custom themes here, relative to this directory. diff --git a/docs/requirements.txt b/docs/requirements.txt index ab7825a..98003bb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,4 +3,4 @@ # under `install_requires` in `setup.cfg` is also listed here! sphinx>=3.2.1 sphinx-autodoc-typehints>=1.12.0 -# sphinx_rtd_theme +sphinx_rtd_theme