diff --git a/.github/workflows/docs_preview.yml b/.github/workflows/docs_preview.yml new file mode 100644 index 0000000..6825462 --- /dev/null +++ b/.github/workflows/docs_preview.yml @@ -0,0 +1,65 @@ +name: Docs Preview + +on: + pull_request: + types: + - opened + - synchronize + - reopened + - edited + - closed + branches: + - "main" + workflow_dispatch: + +concurrency: preview-${{github.ref}} + +jobs: + preview: + runs-on: ubuntu-latest + # only run if from the same repository, not a fork + if: github.event.pull_request.head.repo.full_name == github.repository + permissions: + contents: write + pull-requests: write + defaults: + run: + shell: bash -l {0} + + steps: + # Checkout current git repository + - name: Checkout + uses: actions/checkout@v4 + + # setup python env + - uses: actions/setup-python@v5 + if: github.event.action != 'closed' # Skip the build if the PR has been closed; just run the clean up steps + with: + python-version: "3.x" + + - uses: astral-sh/setup-uv@v6 + + - id: install_pandoc + run: sudo apt-get install pandoc + + # Make API docs + - name: Make API docs + if: github.event.action != 'closed' + run: uvx nox -s build_api_docs + + # Build the documentation + - name: Build the documentation + if: github.event.action != 'closed' + run: uvx nox -s docs --non-interactive -- docs/_build/html + + # Deploy the preview of the docs + - name: Deploy Preview + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: docs/_build/html + preview-branch: gh-pages + # custom-url: + umbrella-dir: pr-preview + action: auto + deploy-repository: ${{ github.repository }} + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..13cb06d --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,51 @@ +name: documentation + +on: + push: + branches: + - main + workflow_dispatch: + +# This job installs dependencies, builds the html, and pushes it to gh-pages +jobs: + docs: + runs-on: ubuntu-latest + permissions: + contents: write + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} # only run one of these jobs at a time + defaults: + run: + shell: bash -l {0} + + steps: + # Checkout current git repository + - name: Checkout + uses: actions/checkout@v4 + + # setup python env + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - uses: astral-sh/setup-uv@v6 + + - id: install_pandoc + run: sudo apt-get install pandoc + + # Make API docs + - name: Make API docs + run: uvx nox -s build_api_docs + + # Build the documentation + - name: Build the documentation + run: uvx nox -s docs --non-interactive -- docs/_build/html + + # Deploy the HTML to gh-pages branch + - name: GitHub Pages action + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/_build/html + publish_branch: gh-pages + force_orphan: true diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 37b858f..007ff64 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -92,4 +92,3 @@ repos: hooks: - id: check-dependabot - id: check-github-workflows - - id: check-readthedocs diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index 6dc66a1..0000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,18 +0,0 @@ -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -version: 2 - -build: - os: ubuntu-22.04 - tools: - python: "mambaforge-22.9" - jobs: - install: - - pip install --no-deps . - -sphinx: - configuration: docs/conf.py - -conda: - environment: environment.yml diff --git a/README.md b/README.md index 8fa6d21..c7e8429 100644 --- a/README.md +++ b/README.md @@ -138,13 +138,14 @@ Steps: - create a new folder : `staged-recipes/recipes/samplepackagename` - copy your `meta.yaml` file into this folder, remove the `meta.yaml` from wherever it was generated. - commit and push your changes to your fork, and in the main [repository](https://github.com/conda-forge/staged-recipes) open a PR. -13) Set up ReadTheDocs for the documentation website - - log into ReadTheDocs using your GitHub account. - - click `Add project` and ssearch for your repository. - - Chose your project name, ideally its the same as your package name, but it doesn't have to be. If it's different, update the badge below: `[rtd-link]: https://samplepackagename.readthedocs.io/en/latest/?badge=latest` - - Go to `settings` to update anything you'd like - - check `Build pull requests for this project`. - - for each commit to main, ReadTheDocs should automatically update the documentation website. Also, in PR's there should be a link to view the new docs to check them before merging the PR. +13) Set up GitHub Pages to host the documentation website + - this will only work for a public repository + - On GitHub, go to your repositories settings + - for `Source`, choose "Deplot from a branch" + - for `Branch`, choose "gh-pages" + - for `Select folder`, choose "root" + - optionally choose a custom URL and hit save + - for every push to `main` (from a PR), the site will be updated 14) Finalize - remove all the above instructions and raise any issues in this template's repository if you have any suggestion or found any errors in this template! - if you want, please submit a PR to this repository to add your package to this list at the top of this README to showcase it! @@ -153,7 +154,7 @@ Steps: Short description of your package. [![Actions Status][actions-badge]][actions-link] -[![Documentation Status][rtd-badge]][rtd-link] +[![Documentation Status][website-badge]][website-link] [![PyPI version][pypi-version]][pypi-link] [![Conda-Forge][conda-badge]][conda-link] @@ -173,8 +174,8 @@ Short description of your package. [pypi-link]: https://pypi.org/project/samplepackagename/ [pypi-platforms]: https://img.shields.io/pypi/pyversions/samplepackagename [pypi-version]: https://img.shields.io/pypi/v/samplepackagename -[rtd-badge]: https://readthedocs.org/projects/samplepackagename/badge/?version=latest -[rtd-link]: https://samplepackagename.readthedocs.io/en/latest/?badge=latest +[website-badge]: https://github.com/mdtanker/python_package_template/actions/workflows/pages/pages-build-deployment/badge.svg +[website-link]: https://mdtanker.github.io/python_package_template/ diff --git a/docs/api/packagename.rst b/docs/api/packagename.rst deleted file mode 100644 index 894c628..0000000 --- a/docs/api/packagename.rst +++ /dev/null @@ -1,18 +0,0 @@ -samplepackagename package -=================== - -.. automodule:: samplepackagename - :members: - :show-inheritance: - :undoc-members: - -Submodules ----------- - -samplepackagename.module1 module --------------------------- - -.. automodule:: samplepackagename.module1 - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/api/samplepackagename.rst b/docs/api/samplepackagename.rst deleted file mode 100644 index 8f56933..0000000 --- a/docs/api/samplepackagename.rst +++ /dev/null @@ -1,18 +0,0 @@ -samplepackagename package -========================= - -.. automodule:: samplepackagename - :members: - :show-inheritance: - :undoc-members: - -Submodules ----------- - -samplepackagename.module1 module --------------------------------- - -.. automodule:: samplepackagename.module1 - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/conf.py b/docs/conf.py index a77b1d8..d3dc729 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,6 +18,8 @@ "sphinx_copybutton", # "sphinx.ext.viewcode", "nbsphinx", + # githubpages just adds a .nojekyll file + "sphinx.ext.githubpages", ] source_suffix = [".rst", ".md"] diff --git a/docs/examples/index.md b/docs/examples/index.md index 5ec8d89..cb830d3 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -1,7 +1,11 @@ # Examples + +notebook1 +notebook2 +notebook3 ``` +--> diff --git a/docs/how_to/index.md b/docs/how_to/index.md index b41167f..37b78b5 100644 --- a/docs/how_to/index.md +++ b/docs/how_to/index.md @@ -1,7 +1,11 @@ # How-To Guides + +notebook1 +notebook2 +notebook3 ``` +--> diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 674d9b9..1fa3282 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -4,9 +4,14 @@ These tutorials are designed to introduce a new user to the software. They expect you to be familiar with Python and have the package [successfully installed](../install.md). You should follow these in order, then refer to the [how-to guides](../how_to/index.md) for more in-depth guides for specific features. + + +notebook1 +notebook2 +notebook3 ``` +-->