mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Creating Documentation page (#12486)

Browse Source 
* Updated the creating documentation page with more informationg on
building and viewing. Fixed some formatting and markup issues with
existing text.

* Minor corrections

* Revert "Minor corrections"

This reverts commit efbe4bde55.

* Minor corrections

* Update Creating-Documentation.md

* Update Creating-Documentation.md

* Update Creating-Documentation.md

Co-authored-by: Jellyfrog <Jellyfrog@users.noreply.github.com>
This commit is contained in:
yrebrac
2021-02-02 06:50:52 +11:00
committed by GitHub
parent 50b99a4f1a
commit 3251cc8ac0
1 changed files with 103 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
doc/Developing/Creating-Documentation.md
View File

@@ -1,53 +1,49 @@
source: Developing/Creating-Documentation.md
source: Developing/Creating-Documentation.md
path: blob/master/doc/
# Creating Documentation
One of the goals of the LibreNMS project is to enable users to get all
of the help they need from our documentation.
One of the goals of the LibreNMS project is to enable users to get all of the
help they need from our documentation.
The documentation is generated with
[mkdocs](https://www.mkdocs.org/). If you want to build a local copy,
install `mkdocs` and `mkdocs-material`, then run `make docs`. This
produces the HTML in `docs/out` directory.
The documentation uses the [markdown](https://en.wikipedia.org/wiki/Markdown)
markup language and is generated with [mkdocs](https://www.mkdocs.org/). To edit
or create markdown you only need a text editor, but it is recommended to build
your docs before submitting, in order to check them visually. The section on
this page has instructions for this step.
Alternatively you can start a webserver at <http://localhost:8000> for
live preview by executing `mkdocs serve`
### Writing docs
## Writing docs
When you are adding a new feature or extension, we need to have full
documentation to go along with it. It's quite simple to do this:
- Find the relevant directory to store your new document in, General,
Support and Extensions are the most likely choices.
- Think of a descriptive name that's not too long, it should match
what they may be looking for or describes the feature.
- Add the new document into the `nav` section of `mkdocs.yml` if it
needs to appear in the table of contents
- Ensure the first line contains: `source: path/to/file.md` - don't
include the initial `doc/`.
- Find the relevant directory to store your new document in, General, Support
and Extensions are the most likely choices.
- Think of a descriptive name that's not too long, it should match what they may
be looking for or describes the feature.
- Add the new document into the `nav` section of `mkdocs.yml` if it needs to
appear in the table of contents
- Ensure the first line contains: `source: path/to/file.md` - don't include the
initial `doc/`.
- In the body of the document, be descriptive but keep things simple. Some tips:
- If the document could cover different distros like CentOS and
Ubuntu please try and include the information for them all. If
that's not possible then at least put a placeholder in asking for contributions.
- Ensure you use the correct formatting for `commands` and `code
blocks` by wrapping one liners in backticks or blocks in ```.
- Put content into sub-headings where possible to organise the
content.
- If you rename a file, please add a redirect in for the old file by
using `<meta http-equiv="refresh" content="0; url=/NewLocation/" />`
within the old file name.
- If the document could cover different distros like CentOS and Ubuntu please
try and include the information for them all. If that's not possible then at
least put a placeholder in asking for contributions.
- Ensure you use the correct formatting for `commands` and `code blocks` by
wrapping one liners in backticks or blocks in ```.
- Put content into sub-headings where possible to organise the content.
- If you rename a file, please add a redirect in for the old file by using
`<meta http-equiv="refresh" content="0; url=/NewLocation/" />` within the old
file name.
Please ensure you add the document to the relevant section within
`pages` of `mkdocs.yml` so that it's in the correct menu and is built.
Forgetting this step will result in your document never seeing the
light of day :)
Please ensure you add the document to the relevant section within `pages` of
`mkdocs.yml` so that it's in the correct menu and is built. Forgetting this
step will result in your document never seeing the light of day :)
### Formatting docs
## Formatting docs
Our docs are based on Markdown using mkdocs which adheres to markdown
specs and nothing more, because of that we also import a couple of extra libraries:
Our docs are based on Markdown using mkdocs which adheres to markdown specs and
nothing more, because of that we also import a couple of extra libraries:
- pymdownx.tasklist
- pymdownx.tilde
@@ -57,10 +53,77 @@ This means you can use:
- `~~strikethrough~~` to perform ~~strikethrough~~
- [X] `- [X] List items`
- Url's can be made `[like this](http://www.librenms.org)` [like this](http://www.librenms.org)
- Code can be placed in `` for single line or ``` for multiline.
- Code can be placed in \`\` for single line or \`\`\` for multiline.
- `#` Can be used for main headings which translates to a `<h1>` tag,
increasing the `#`'s will increase the hX tags.
- `###` Can be used for sub-headings which will appear in the TOC to
the left.
- `###` Can be used for sub-headings which will appear in the TOC to the left.
[Markdown CheatSheet Link](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
## Building docs
This is achieved with `mkdocs`, a python package.
1. Install the required packages.
```
pip install mkdocs mkdocs-exclude mkdocs-material mkdocs-macros-plugin
```
If you encounter permissions issues, these might be reoslved by using the
user option, with whatever user you are building as, e.g. `-u librenms`
2. A configuration file for building LibreNMS docs is already included in the
distribution: `/opt/librenms/mkdocs.yml`. The various configuration
directives are documented
[here](https://www.mkdocs.org/user-guide/configuration/).
3. Build from the librenms base directory: `cd /opt/librenms`.
4. Building is simple:
```
mkdocs build
```
This will output all the documentation in html format to `/opt/librenms/out`
(this folder will be ignored from any commits).
## Viewing docs
mkdocs includes it's own light-weight webserver for this purpose.
Viewing is as simple as running the following command:
```
$ mkdocs serve
INFO - Building documentation...
<..>
INFO - Documentation built in 12.54 seconds
<..>
INFO - Serving on http://127.0.0.1:8000
<..>
INFO - Start watching changes
```
Now you will find the complete set of LibreNMS documentation by opening your
browser to `localhost:8000`.
Note it is not necessary to `build` before viewing as the `serve` command
will do this for you. Also the server will update the documents it is serving
whenever changes to the markdown are made, such as in another terminal.
### Viewing docs from another machine
By default the server will only listen for connections from the local machine.
If you are building on a different machine you can use the following directive
to listen on all interfaces:
```
mkdocs serve --dev-addr=http://0.0.0.0:8000
```
WARNING: this is not a secure webserver, do this at your own risk, with
appropriate host security and do not leave the server running.
[Markdown CheatSheet Link](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)