From 351738bf0431f979912d01a33c2d3a9c85f7242d Mon Sep 17 00:00:00 2001 From: Brady Planden Date: Thu, 14 Dec 2023 14:55:52 +0000 Subject: [PATCH 1/3] Add switcher.json --- docs/_static/switcher.json | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/_static/switcher.json diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json new file mode 100644 index 000000000..682d19994 --- /dev/null +++ b/docs/_static/switcher.json @@ -0,0 +1,12 @@ +[ + { + "version": "latest", + "url": "https://pybop-docs.readthedocs.io/en/latest/", + "preferred": true + }, + { + "name": "v23.11 (stable)", + "version": "v23.11", + "url": "https://pybop-docs.readthedocs.io/en/latest/" + } + ] From 226670a5eb6024b5dd4ac1a063931368ecb2d4e1 Mon Sep 17 00:00:00 2001 From: Brady Planden Date: Thu, 14 Dec 2023 15:01:00 +0000 Subject: [PATCH 2/3] Remove gh-pages deployment in favour of rtd --- .github/workflows/deploy-docs.yaml | 39 --------------------- pybop/readthedocs.yaml => .readthedocs.yaml | 0 2 files changed, 39 deletions(-) delete mode 100644 .github/workflows/deploy-docs.yaml rename pybop/readthedocs.yaml => .readthedocs.yaml (100%) diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml deleted file mode 100644 index bb64d714d..000000000 --- a/.github/workflows/deploy-docs.yaml +++ /dev/null @@ -1,39 +0,0 @@ -name: Deploy Documentation - -on: - release: - types: [created] - workflow_dispatch: - -permissions: - contents: write # allow write access for docs deployment - -jobs: - build-and-deploy: - runs-on: ubuntu-latest - steps: - - name: Check out PyBOP repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod - - - name: Set up Python 3.11 - id: setup-python - uses: actions/setup-python@v4 - with: - python-version: 3.11 - cache: 'pip' - cache-dependency-path: setup.py - - - name: Install dependencies - run: | - python -m pip install --upgrade pip nox - - name: Using Python 3.11, build the docs - run: nox -s docs - - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/_build/html - publish_branch: gh-pages diff --git a/pybop/readthedocs.yaml b/.readthedocs.yaml similarity index 100% rename from pybop/readthedocs.yaml rename to .readthedocs.yaml From 3ba9a6aa295c5d68e5718187ae1a955dec2e11a4 Mon Sep 17 00:00:00 2001 From: Brady Planden Date: Thu, 14 Dec 2023 15:32:43 +0000 Subject: [PATCH 3/3] Add contributing links, add print version install verification --- CONTRIBUTING.md | 4 ++-- docs/conf.py | 4 ++-- docs/installation.rst | 19 +++++++++++-------- docs/quick_start.rst | 2 +- 4 files changed, 16 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 055221c94..9fecf0c01 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ pip install -e .[all] ``` ## Pre-commit checks -Before you commit any code, please perform the following checks: +Before you commit any code, please perform the following checks using [Nox](https://nox.thea.codes/en/stable/index.html): - [All tests pass](#testing): `$ nox -s unit` @@ -128,7 +128,7 @@ This allows people to (1) use PyBOP without ever importing Matplotlib and (2) co ### Building documentation -We use [Sphinx](http://www.sphinx-doc.org/en/stable/) to build our documentation. A nox session has been created to reduce the overhead when building the documentation locally. To run this session, type +We use [Sphinx](http://www.sphinx-doc.org/en/stable/) to build our documentation. A [Nox](https://nox.thea.codes/en/stable/index.html) session has been created to reduce the overhead when building the documentation locally. To run this session, type ```bash nox -s docs diff --git a/docs/conf.py b/docs/conf.py index 11588cda7..14f8a0b19 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -73,12 +73,12 @@ "navbar_align": "content", "navbar_center": ["navbar-nav", "version-switcher"], "show_version_warning_banner": True, + "footer_start": ["copyright"], + "footer_center": ["sphinx-version"], "switcher": { "json_url": json_url, "version_match": version_match, }, - "footer_start": ["copyright"], - "footer_center": ["sphinx-version"], } html_static_path = ["_static"] diff --git a/docs/installation.rst b/docs/installation.rst index 8fa9cdd1b..3c0080c1d 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -12,13 +12,13 @@ The simplest method to install PyBOP is using pip. Run the following command in .. code-block:: console - $ pip install pybop + pip install pybop This command will download and install the latest stable version of PyBOP. If you want to install a specific version, you can specify the version number using the following command: .. code-block:: console - $ pip install pybop==23.11 + pip install pybop==23.11 Installing the Development Version ---------------------------------- @@ -27,7 +27,7 @@ If you're interested in the cutting-edge features and want to try out the latest .. code-block:: console - $ pip install git+https://github.com/pybop-team/PyBOP.git@develop + pip install git+https://github.com/pybop-team/PyBOP.git@develop Please note that the development version may be less stable than the official releases. @@ -38,21 +38,24 @@ For those who prefer to install PyBOP from a local clone of the repository or wi .. code-block:: console - $ pip install -e "path/to/pybop" + pip install -e "path/to/pybop" In editable mode, changes you make to the source code will immediately affect the PyBOP installation without the need for reinstallation. Verifying Installation ---------------------- -To verify that PyBOP has been installed successfully, try running one of the provided example scripts included in the documentation or repository. If the example executes without any errors, PyBOP is ready to use. +To verify that PyBOP has been installed successfully, try running one of the provided example scripts included in the documentation or repository. If the example executes without any errors, PyBOP is ready to use. Alternatively, you can run the following command in your terminal to check the version of PyBOP that is installed: + +.. code-block:: console + + python -c "import pybop; print(pybop.__version__)" + For Developers -------------- -If you are installing PyBOP for development purposes, such as contributing to the project, please ensure that you follow the guidelines outlined in the contributing guide. It includes additional steps that might be necessary for setting up a development environment, including the installation of dependencies and setup of pre-commit hooks. - -`Contributing Guide <../Contributing.html>`_ +If you are installing PyBOP for development purposes, such as contributing to the project, please ensure that you follow the guidelines outlined in the `Contributing Guide <../Contributing.html>`_. It includes additional steps that might be necessary for setting up a development environment, including the installation of dependencies and setup of pre-commit hooks. Further Assistance ------------------ diff --git a/docs/quick_start.rst b/docs/quick_start.rst index e8ebbc0cf..683c82b40 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -14,7 +14,7 @@ To begin using PyBOP: .. code-block:: console - $ pip install pybop + pip install pybop For detailed installation instructions, including how to install specific versions or from source, see the :ref:`installation` section.