CONTRIBUTING.md

Contributing

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to the eccenca Corporate Memory documention project.

How Can I Contribute?

Report Bugs

If you found a bug and its easy to fix, you can just click the edit button and fix it yourself sending a pull request 🤓. However, you can also file a bug in the issue tracker of this project.

Suggest Enhancements

You always can suggest enhancements in the issue tracker of this project.

Send Pull Requests

We are open for contributions via pull request. Try to test your contribution locally before pushing your changes.

What should I know before I get started?

Extend section

This documentation project is made with mkdocs and the material theme for mkdocs. The documentation is written in markdown and the project dependency management is done by poetry. We suggest to use a specialized markdown editor such as obsidian if you plan to not just fix a typo.

The following tools you need locally to get started:

• poetry
• task
• git, markdown editor

On a few OS distributions (e.g. Arch Linux) the tool/binary is named go-task.

The following shell session demonstrates the local workflow (after you forked the repository):

$ git clone <your repository fork>
Cloning into 'documentation.eccenca.com'...
...
$ cd documentation.eccenca.com/
$ task serve
task: [install] poetry install
Creating virtualenv in ...
Installing dependencies from lock file

Package operations: 62 installs, 0 updates, 0 removals
...
task: [serve] poetry run mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 20.03 seconds
INFO     -  [16:25:36] Watching paths for changes: 'docs', 'mkdocs.yml', 'overrides'
INFO     -  [16:25:36] Serving on http://127.0.0.1:8000/

After that, you can go to http://127.0.0.1:8000/ and start changing / adding files in the docs directory. Changes are served live on localhost.

Note that some python packages need corresponding C libraries, which you may have to install as well. Have a look at the mkdocs-material documentation and the build plan for a list.

Repository rules

• always create a directory + index.md, e.g. my-topic/index.md (Example)
• add new pages to the .pages file to add them in the right order and with correct title to the menu (Example)
• put images side by side to the index.md (Example)
• do not use images for icons esp. icons from the application
  • use eccenca icons, e.g. :eccenca-application-queries: -> list
  • use theme icons where no eccenca icon is available -> list
• name image files properly (not just Screenshot.xxx.png, Example)
• used advanced features where suitable
  • Admonitions (esp. use notes and warnings where needed)
  • Code Blocks (e.g. enable highlightning and add a title)
  • Content Tabs (to structure complex pages)
• code blocks:
  • do not use line numbers except you refer to it in the text
  • use correct syntax highlightning (often used: shell-session, bash, sparql, turtle, json) -> list of syntax IDs
  • do not confuse shell-session with bash (the first is a terminal output, the latter a script syntax)
  • when using shell-session, use $ as the prompt
• Links:
  • do not use absolute links for internal documents, e.g. https://documentation.eccenca.com/latest/...
  • do not use base-relative links, e.g. /automate/...
  • use relative links to index.md files