mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
6575042f5f
* clean up all but header incrementing in Creating-Transport.md * make Device-Dependencies.md mdl happy * make Entities.md as mdl happy as possible... one long table line left * make mdl as happy as possible for index.md * clean up Introduction.md as much as possible * minor formatting cleanup... move each icon onto its own row * make ack and notes the same style * clean Macros.md up * clean Rules.md up as much as possible * tweak one line a bit to get it to format a bit nicer * a bit more format tweaking, making sure it does not sure with > * clean up as much as possible for Templates.md * make Testing.md as mdl happy as possibly * clean Transports.md up as much as possible * clean as many issues as possible for Alerts.md * clean up as much of ARP.md as possible * clean up as much as possible for Bills.md * make DeviceGroups.md as mdl happy as possible * cleanup Devices.md * make as mdl happy as possible Inventory.md and index.md * mdl cleanup for Logs.md and PortGroups.md * make Ports.md and Routing.md as happy as possible * clean up Services.md, Switching.md, and Systems.md as much as possible * more markup cleanup * lots more md cleanup udner Devloping/ * reapply bits from #10343 that accidentally got removed when merging
66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
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.
|
|
|
|
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.
|
|
|
|
Alternatively you can start a webserver at <http://localhost:8000> for
|
|
live preview by executing `mkdocs serve`
|
|
|
|
### 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/`.
|
|
- 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 formating 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 :)
|
|
|
|
### 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:
|
|
|
|
- pymdownx.tasklist
|
|
- pymdownx.tilde
|
|
|
|
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.
|
|
- `#` 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.
|
|
|
|
[Markdown CheatSheet Link](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|