From 840cbaaf873a19415f4045f6248ae17d70a5a1b3 Mon Sep 17 00:00:00 2001 From: Henrik Finsberg Date: Mon, 23 Dec 2024 09:35:30 +0100 Subject: [PATCH 1/2] Upgrade to jupyterbook version 2 --- .github/workflows/build_docs.yml | 36 ++++++ .github/workflows/deploy_docs.yml | 41 +++++++ .github/workflows/main.yml | 70 ------------ .gitignore | 179 +++++++++++++++++++++++++++++- docs/_config.yml | 41 ------- docs/_toc.yml | 49 -------- docs/documentation.md | 2 +- docs/environment.md | 4 +- docs/jupyter-book.md | 4 +- docs/myst.yml | 70 ++++++++++++ docs/packages.md | 1 - docs/python-conversion.md | 2 +- docs/python-coverage.md | 2 +- docs/python-linting.md | 2 +- docs/python-testing.md | 2 +- docs/repositories.md | 2 +- docs/structure.md | 10 +- requirements.txt | 2 +- 18 files changed, 340 insertions(+), 179 deletions(-) create mode 100644 .github/workflows/build_docs.yml create mode 100644 .github/workflows/deploy_docs.yml delete mode 100644 .github/workflows/main.yml delete mode 100644 docs/_config.yml delete mode 100644 docs/_toc.yml create mode 100644 docs/myst.yml diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 0000000..6562513 --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,36 @@ +name: Build documentation + +on: + pull_request: + branches: [main] + workflow_call: + workflow_dispatch: + + +jobs: + + build: + runs-on: ubuntu-22.04 + env: + PUBLISH_DIR: ./docs/_build/html + + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install dependencies + run: python3 -m pip install . + + - name: Build docs + run: cd docs && jupyter book build --html --check-links + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ${{ env.PUBLISH_DIR }} diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml new file mode 100644 index 0000000..03d37b2 --- /dev/null +++ b/.github/workflows/deploy_docs.yml @@ -0,0 +1,41 @@ +name: Publish documentation + +on: + push: + branches: [main] + workflow_dispatch: + + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + + build: + uses: ./.github/workflows/build_docs.yml + + deploy: + needs: build + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml deleted file mode 100644 index c6a1d17..0000000 --- a/.github/workflows/main.yml +++ /dev/null @@ -1,70 +0,0 @@ -name: Deploy static content to Pages - -# Only run this when the master branch changes -on: - push: - branches: - - "**" - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow one concurrent deployment -concurrency: - group: "pages" - cancel-in-progress: true - -env: - # Directory that will be published on github pages - PUBLISH_DIR: ./docs/_build/html - -# This job installs dependencies, build the book, and pushes it to `gh-pages` -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Set up Python 3 - uses: actions/setup-python@v4 - with: - python-version: "3.10" - - - name: Install requirements - run: python -m pip install -r requirements.txt - - - name: Build the book - shell: bash -l {0} - run: jupyter book build -W docs - - - name: Upload artifact - uses: actions/upload-pages-artifact@v1 - with: - path: ${{ env.PUBLISH_DIR }} - - # Single deploy job since we're just deploying - deploy: - if: github.ref == 'refs/heads/main' - needs: build - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Setup Pages - uses: actions/configure-pages@v2 - - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v1 diff --git a/.gitignore b/.gitignore index 58f1173..8715103 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,178 @@ docs/_build -sc_webpage_env -*.egg-info +_build +# Created by https://www.toptal.com/developers/gitignore/api/python +# Edit at https://www.toptal.com/developers/gitignore?templates=python + +### Python ### +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm.toml + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ + +### Python Patch ### +# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration +poetry.toml + +# ruff +.ruff_cache/ + +# LSP config files +pyrightconfig.json + +# End of https://www.toptal.com/developers/gitignore/api/python diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 5894c21..0000000 --- a/docs/_config.yml +++ /dev/null @@ -1,41 +0,0 @@ -# Book settings -# Learn more at https://jupyterbook.org/customize/config.html - -title: Scientific Computing -author: Henrik Finsberg and Jørgen Dokken -logo: "_static/logo.png" -copyright: "2022" --description: Developing tools for high performance computing, and applying novel simulation techniques to complex physical processes affecting human health. - -# Force re-execution of notebooks on each build. -# See https://jupyterbook.org/content/execute.html -execute: - execute_notebooks: cache - -# Information about where the book exists on the web -repository: - url: https://github.com/scientificcomputing/scientificcomputing.github.io # Online location of your book - -html: - use_issues_button: true - use_repository_button: true - extra_navbar: See more at simula.no - -parse: - myst_enable_extensions: - - amsmath - - dollarmath - - linkify - - -sphinx: - config: - html_last_updated_fmt: "%b %d, %Y" - bibtex_bibfiles: ["references.bib"] - suppress_warnings: ["bibtex.duplicate_citation"] # If the same paper is cited in multiple files - - extra_extensions: - - "sphinx.ext.autodoc" - - "sphinx.ext.napoleon" - - "sphinx.ext.viewcode" - - "sphinxcontrib.bibtex" diff --git a/docs/_toc.yml b/docs/_toc.yml deleted file mode 100644 index f3f9332..0000000 --- a/docs/_toc.yml +++ /dev/null @@ -1,49 +0,0 @@ -format: jb-book -root: index - -parts: - - caption: Publication list - chapters: - - file: repositories - - file: packages - - - caption: Guidelines for papers with code - chapters: - - file: papers-with-code - - file: structure - - file: data - - file: environment - - file: scripts - - - caption: Git/Github - chapters: - - file: version_control - - file: gh-workflows - - file: gh-packages - - file: gh-citable - - file: gh-issues - - - caption: Documentation - chapters: - - file: documentation - - file: jupyter-book - - - caption: Python - chapters: - - file: python-packaging - - file: python-testing - - file: python-coverage - - file: python-linting - - file: python-pre-commit - - file: python-conversion - - - caption: Miscellaneous - chapters: - - file: license - - file: software-citation - - file: resources - - file: misc - - - caption: Contact - chapters: - - file: contact diff --git a/docs/documentation.md b/docs/documentation.md index e19c436..ebdb4b8 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -12,4 +12,4 @@ The documentation should cover at least the following: First of all, it is nice to get a short high level introduction to what problems are solved in the paper. Second, the actual code you use is probably not documented in the paper itself so there should be some explanation about how a user can run the code and reproduce the results. ## Hosting your documentation online -While you could put all of the documentation in a README file you could also put it at a webpage, similar to the page you are reading right now. Once you have a README file it is pretty simple to turn this into a nice looking webpage using [JupyterBook](https://jupyterbook.org) and [GitHub pages](https://pages.github.com). You can read more about how to set up [Jupyter book](jupyter-book) and how to [publish the book to GitHub pages](publishing-book). +While you could put all of the documentation in a README file you could also put it at a webpage, similar to the page you are reading right now. Once you have a README file it is pretty simple to turn this into a nice looking webpage using [JupyterBook](https://jupyterbook.org) and [GitHub pages](https://pages.github.com). You can read more about how to set up [Jupyter book](jupyter-book) and how to [publish the book to GitHub pages](#publishing-book). diff --git a/docs/environment.md b/docs/environment.md index d253fa0..37e4c38 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -5,9 +5,9 @@ Being able to create a reproducible environment is probably one of the biggest c When reproducing the results of a research paper you would like to use the same environment as was used when writing the paper. This can be achieved by publishing a Docker image. -We recommend that you publish a docker image every time you create a new version of your code (see [](version-control-tag) for more info about how to create a version). +We recommend that you publish a docker image every time you create a new version of your code (see [](#version-control-tag) for more info about how to create a version). -You can read more about how to publish a Docker image in [](publish-docker) and you can see an example `Dockerfile` in the [example-paper repo](https://github.com/scientificcomputing/example-paper/blob/main/Dockerfile). +You can read more about how to publish a Docker image in [](#publish-docker) and you can see an example `Dockerfile` in the [example-paper repo](https://github.com/scientificcomputing/example-paper/blob/main/docker/Dockerfile). ## Language specific dependencies diff --git a/docs/jupyter-book.md b/docs/jupyter-book.md index 5227a54..d96b496 100644 --- a/docs/jupyter-book.md +++ b/docs/jupyter-book.md @@ -7,7 +7,7 @@ Examples can be found at: - [FEniCSx tutorial](https://jorgensd.github.io/dolfinx-tutorial/) - [Simcardems](https://computationalphysiology.github.io/simcardems/) - [Oasisx](https://computationalphysiology.github.io/oasisx/) -- [Cardiac Geometries](https://computationalphysiology.github.io/cardiac_geometries/) +- [Cardiac Geometries](https://computationalphysiology.github.io/cardiac-geometries/) - [Action Potential Features](https://computationalphysiology.github.io/ap_features/) - [Cardiac MPS Motion](https://computationalphysiology.github.io/mps_motion/) @@ -33,7 +33,7 @@ A configuration file for the book, see: [Jupyterbook - Configuration reference]( (publishing-book)= ## Publishing book -The book can be published following [Publishing to Pages](publishing-to-pages), where +The book can be published following [Publishing to Pages](#publishing-to-pages), where step 3 in the official action would be calling `jupyter book build .` to generate the documentation at `_build/html`, which in turn is the folder we upload as a Github page. A Github action showing some of the steps can be found at [Actions/deploy-pages](https://github.com/actions/deploy-pages#usage). diff --git a/docs/myst.yml b/docs/myst.yml new file mode 100644 index 0000000..9c657f6 --- /dev/null +++ b/docs/myst.yml @@ -0,0 +1,70 @@ +# See docs at: https://mystmd.org/guide/frontmatter +version: 1 +project: + id: 867a190a-9c64-4dd1-bc79-25cb4bdd3a53 + title: Scientific Computing + description: Developing tools for high performance computing, and applying novel simulation techniques to complex physical processes affecting human health. + keywords: + - Scientific Computing + - Computational Physiology + - Numerical Analysis + - High Performance Computing + - Simulation + authors: + - Henrik Finsberg + - Jørgen Dokken + github: https://github.com/scientificcomputing/scientificcomputing.github.io + # To autogenerate a Table of Contents, run "jupyter book init --write-toc" + toc: + - file: index.md + - title: Publication list + children: + - file: repositories.md + - file: packages.md + - title: Guidelines for papers with code + children: + - file: papers-with-code.md + - file: structure.md + - file: data.md + - file: environment.md + - file: scripts.md + + - title: Git/Github + children: + - file: version_control.md + - file: gh-workflows.md + - file: gh-packages.md + - file: gh-citable.md + - file: gh-issues.md + + - title: Documentation + children: + - file: documentation.md + - file: jupyter-book.md + + - title: Python + children: + - file: python-packaging.md + - file: python-testing.md + - file: python-coverage.md + - file: python-linting.md + - file: python-pre-commit.md + - file: python-conversion.md + + - title: Miscellaneous + children: + - file: license.md + - file: software-citation.md + - file: resources.md + - file: misc.md + + - title: Contact + children: + - file: contact.md + +site: + template: book-theme + options: + # favicon: favicon.ico + logo: _static/logo.png + logo_dark: _static/logo.png diff --git a/docs/packages.md b/docs/packages.md index 3f65509..96d7f39 100644 --- a/docs/packages.md +++ b/docs/packages.md @@ -14,7 +14,6 @@ A list scientific software (and corresponding publication) developed by personne If you package is missing from the list, go to [Add new package](https://github.com/scientificcomputing/scientificcomputing.github.io/issues/new?assignees=&labels=new-package&template=package.yml&title=%5BAdd+package%5D%3A+) -## References ```{bibliography} :filter: docname in docnames diff --git a/docs/python-conversion.md b/docs/python-conversion.md index b6e661e..d1ea852 100644 --- a/docs/python-conversion.md +++ b/docs/python-conversion.md @@ -7,7 +7,7 @@ One can use [jupytext](https://jupytext.readthedocs.io) jupytext --to=ipynb --output=path_to_nb.ipynb ``` -The Python file should follow the conventions of the [light format](https://jupytext.readthedocs.io/en/latest/formats.html#the-light-format) for appropriate rendering. +The Python file should follow the conventions of the [light format](https://jupytext.readthedocs.io/en/latest/formats-scripts.html#the-light-format) for appropriate rendering. ## Notebook -> Python You can add meta-data to your notebook, making it auto convert to a Python-file at saving (using JupyterLab). This can be achieved by pressing `ctrl+shift+c` and choose `Pair notebook with light script`. diff --git a/docs/python-coverage.md b/docs/python-coverage.md index 3d26c4d..f5c8dfb 100644 --- a/docs/python-coverage.md +++ b/docs/python-coverage.md @@ -4,7 +4,7 @@ When creating a Python package, it can be very useful to know what part of your We recommend using [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) which extends the [pytest](./python-testing.md) suite with a coverage report of your package. -We add to the `addopts` section of the `[tool.pytest.ini_options]` table of [pyproject.toml](content:pyproject): +We add to the `addopts` section of the `[tool.pytest.ini_options]` table of [pyproject.toml](#content:pyproject): ```toml addopts = [ # Other options diff --git a/docs/python-linting.md b/docs/python-linting.md index 47d36fa..6a3d70d 100644 --- a/docs/python-linting.md +++ b/docs/python-linting.md @@ -42,7 +42,7 @@ and be executed as ```bash python -m mypy ``` -We add the following options to [pyproject.toml](content:pyproject) +We add the following options to [pyproject.toml](#content:pyproject) ```toml [tool.mypy] ignore_missing_imports = true diff --git a/docs/python-testing.md b/docs/python-testing.md index dbfa5b4..bab542d 100644 --- a/docs/python-testing.md +++ b/docs/python-testing.md @@ -16,7 +16,7 @@ python -m pytest ``` Pytest will then find all files with names like `test_*.py` and `*_test.py`, see: [Conventions for test discovery](https://docs.pytest.org/en/latest/explanation/goodpractices.html#test-discovery) for more information. -We add the following information to [pyproject.toml](content:pyproject) under table header: `[project.optional-dependencies]` +We add the following information to [pyproject.toml](#content:pyproject) under table header: `[project.optional-dependencies]` ```toml [project.optional-dependencies] # Other entries diff --git a/docs/repositories.md b/docs/repositories.md index 763f530..6113e6f 100644 --- a/docs/repositories.md +++ b/docs/repositories.md @@ -15,7 +15,7 @@ A list of repositories used in research in the Scientific Computing Department f If you repository is missing from the list, go to [Add new repository](https://github.com/scientificcomputing/scientificcomputing.github.io/issues/new?assignees=&labels=new-repo&template=repository.yml&title=%5BAdd+repo%5D%3A+) -## References + ```{bibliography} :filter: docname in docnames ``` diff --git a/docs/structure.md b/docs/structure.md index 655121e..ec14b37 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -38,23 +38,23 @@ You can also check out than contains an interactive e This is the folder containing the actual scripts for running simulations and creating figures and tables. How you organize this folder will depend on the project ### `data` -This is the folder containing the data you are using in your paper. This folder should also contain a `README.md` file with information about what files are expected to be present in this folder. You might be in a situation where you cannot put the data in the repository, either because the data is too large, or the data is not shareable. In this case the README file should contain information about this. You can read more about data at [](data-main). +This is the folder containing the data you are using in your paper. This folder should also contain a `README.md` file with information about what files are expected to be present in this folder. You might be in a situation where you cannot put the data in the repository, either because the data is too large, or the data is not shareable. In this case the README file should contain information about this. You can read more about data at [](#data-main). ### `LICENSE` -A LICENSE contains information about what people can do with the code in your repository. Without a license, no one are allowed to do anything to the code. You can read more about licensing [here](docs-license). +A LICENSE contains information about what people can do with the code in your repository. Without a license, no one are allowed to do anything to the code. You can read more about licensing [here](#docs-license). ## Files we recommend you to have ### `docs` -The `docs` folder contains files for building the documentation. See [](docs-main) for more info. +The `docs` folder contains files for building the documentation. See [](#docs-main) for more info. ### `.github` The `.github` folder is a special folder that contains GitHub specific files such as workflows and issue templates. An [issue template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) is useful if you want user to submit issues and feedback in a structured manner. For example, you want the user submitting an issue to provide information such as which operating system was used, how was the dependencies installed, what was the expected and actual behavior. -[GitHub workflows](https://docs.github.com/en/actions/using-workflows) are webhooks that will trigger when certain actions occur in your repository. For example you could set up a workflow to run your tests every time someone pushes to your repository. If you want to host documentation, then we recommend to set up a workflow to build and deploy the documentation on every push to the main branch (see [](docs-main) for more info). If you provide a `Dockerfile`, then we recommend to deploy a docker image on every new version of your code (see [](version-control-tag) for more info). +[GitHub workflows](https://docs.github.com/en/actions/using-workflows) are webhooks that will trigger when certain actions occur in your repository. For example you could set up a workflow to run your tests every time someone pushes to your repository. If you want to host documentation, then we recommend to set up a workflow to build and deploy the documentation on every push to the main branch (see [](#docs-main) for more info). If you provide a `Dockerfile`, then we recommend to deploy a docker image on every new version of your code (see [](#version-control-tag) for more info). The [example-paper](https://github.com/scientificcomputing/example-paper) contains both of these workflows as well as an issue template. @@ -68,7 +68,7 @@ A citation file is nice to have in your repo so that people easily can see how t ### `Dockerfile` -A [`Dockerfile`](https://docs.docker.com/engine/reference/builder/docker ) is a file containing commands for recreating the environment for running the code. Here you first need to define a base image and then list the commands for installing all the necessary dependencies. If you don't know which base image to use, then [ubuntu](https://hub.docker.com/_/ubuntu) is a good choice. See [](environment-main) for more information about how to specify a reproducible environment. +A [`Dockerfile`](https://docs.docker.com/reference/dockerfile/) is a file containing commands for recreating the environment for running the code. Here you first need to define a base image and then list the commands for installing all the necessary dependencies. If you don't know which base image to use, then [ubuntu](https://hub.docker.com/_/ubuntu) is a good choice. See [](#environment-main) for more information about how to specify a reproducible environment. ### `requirements.txt` In addition to the `Dockerfile` that contains instructions on how to reproduce the environment, it is good practice to provide the list of dependencies in a language specific file. For Python this can be done using a `requirements.txt` file. Other languages have other types of configuration files (`Cargo.toml` in Rust, `Project.toml` for Julia, `CmakeLists.txt` for C/C++ and so on). diff --git a/requirements.txt b/requirements.txt index 811276d..7b43756 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,2 @@ -jupyter-book>=0.13.2 +jupyter-book==2.0.0a0 pre-commit From 9af5b108c9a909b3e6f7251ec51c8bcd224026e6 Mon Sep 17 00:00:00 2001 From: Henrik Finsberg Date: Mon, 23 Dec 2024 13:19:36 +0100 Subject: [PATCH 2/2] Upate readme --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bba772e..3cf4a3f 100644 --- a/README.md +++ b/README.md @@ -27,15 +27,21 @@ Next ensure that the webpage builds, this can be done with python3 -m venv sc_webpage_env source sc_webpage_env/bin/activate python3 -m pip install . -python3 -m jupyter book build -W ./docs +cd docs +jupyter book build --html --check-links --strict ``` -Inspect the webpage locally by opening `./docs/_build/html/index.html` and navigating to the appropriate page. +Inspect the webpage locally by running +```bash +python3 -m http.server -d _build/html 8000 +``` +and opening a browser at `http://localhost:8000`. + Before you push the changes, ensure that the text is properly formatted, run ```bash -pre-commit +pre-commit run --all ``` Then, make corrections and commit any changes before re-running pre-commit.