hydrus/docs/about_docs.md

32 lines
1.2 KiB
Markdown
Raw Normal View History

2022-02-15 11:44:29 +00:00
# About These Docs
2022-02-22 23:35:58 +00:00
The Hydrus docs are built with [MkDocs](https://www.mkdocs.org/) using the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. The .md files in the `docs` directory are converted into nice html in the `help` directory. This is done automatically in the built releases, but if you run from source, you will want to build your own.
2022-02-15 11:44:29 +00:00
## Local Setup
2022-02-22 23:35:58 +00:00
To see or work on the docs locally, [install `mkdocs-material`](https://squidfunk.github.io/mkdocs-material/getting-started/):
2022-02-15 11:44:29 +00:00
The recommended installation method is `pip`:
```
pip install mkdocs-material
```
2022-02-22 23:35:58 +00:00
## Building
2022-02-15 11:44:29 +00:00
2022-02-22 23:35:58 +00:00
To build the help, run:
2022-02-15 11:44:29 +00:00
```
2022-02-22 23:35:58 +00:00
mkdocs build -d help
2022-02-15 11:44:29 +00:00
```
2022-02-22 23:35:58 +00:00
In the base hydrus directory (same as the `mkdocs.yml` file), which will build it into the `help` directory. You will then be good!
2022-02-15 11:44:29 +00:00
2022-02-22 23:35:58 +00:00
Repeat the command and MkDocs will clear out the old directory and update it, so you can fold this into any update script.
2022-02-15 11:44:29 +00:00
2022-02-22 23:35:58 +00:00
## Live Preview
2022-02-15 11:44:29 +00:00
2022-02-22 23:35:58 +00:00
To edit the `docs` directory, you can run the live preview development server with:
2022-02-15 11:44:29 +00:00
```
2022-02-22 23:35:58 +00:00
mkdocs serve
2022-02-15 11:44:29 +00:00
```
2022-02-22 23:35:58 +00:00
Again in the base hydrus directory. It will host the help site at [http://127.0.0.1:8000/](http://127.0.0.1:8000/), and when you change a file, it will automatically rebuild and reload the page in your browser.