Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: provide rudimentary instructions on how to build website locally #98

Merged
merged 2 commits into from
Sep 7, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .codespellrc
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[codespell]
skip = .git,*.pdf,*.svg,venvs
skip = .git,*.pdf,*.svg,venvs,venv,site
#
# ignore-words-list =
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,17 @@ complete word
* **license** (**not** licence); in general, prefer American spelling
* limited use of "please"
* steps should start with 1, not 0

## HOWTO

This handbook uses [mkdocs](https://www.mkdocs.org/) to render the handbook written as a collection of markdown files into a website.
If you would like to render it locally, you would need to create and configure a python environment according to configuration provided in [requirements.txt](./requirements.txt) file, e.g. via

python3 -m venv venv && source venv/bin/activate && python3 -m pip install -r requirements.txt

And your current session would already be using that virtual Python environment, which you could deactivate by executing `deactivate` command.
If in the future you would need to activate it, just `source venv/bin/activate` again.

After that you can either
- do one time manual build using `mkdocs build` and find built website under `site/` folder.
- run `mkdocs serve` which would not only build website and start a local webserver for you to visit rendered version at e.g., http://0.0.0.0:8000/, but also it would automatically re-build if you change any source markdown or configuration file.