Organize Tool Documentation

Documentation for:

• l3d
• d4d
• Composer Plugins
• and further more

changed title from Organize Toll Documentation to Organize Tool Documentation

assigned to @jurgenhaas

marked this issue as related to docker/l3d#64 (closed)

removed the relation with docker/l3d#64 (closed)

@danielspeicher @felixhaeberle we now have a framework for the documentation and it's amazingly easy to use within our L3D environment. Please follow these steps:

l3d selfupdate 2.0.0-beta3
l3d reset
cd ~
git@gitlab.lakedrops.com:devops-tools/documentation.git
cd documentation
l3d .

With this you get inside L3D of this project and can easily start the docs-server: ahoy mkdocs up, start the docker container and the mkdocs server, also prints a url that you can open in your browser. Now you can edit the docs and the browser will auto-refresh the docs for you.

Do you want to install this theme? It's really straightforward to install it, I think :) https://github.com/squidfunk/mkdocs-material

Yes, that was already installed but not yet configured. It is now ! Looks awesome

Also, the latest version has support for PlantUML installed as well. Write your UML diagrams in /docs/diagrams/src and you get SVG files automatically in /docs/diagrams/out which can be included in your pages. Example provided on the front page.

mentioned in commit c5e84f01

mentioned in commit 184864f4

mentioned in commit ansible/roles/user-management@c412d4bc

mentioned in commit ansible/plugins/serverdensity@ef5d37ff

mentioned in commit ansible/roles/elasticsearch@3ae2c660

mentioned in commit ansible/roles/serverdensity@4dad5653

mentioned in commit ansible/roles/letsencrypt@1c523954

mentioned in commit ansible/roles/borgbackup@b866f88a

mentioned in commit ansible/roles/elastalert@b4c272e7

mentioned in commit ansible/roles/packetbeat@737293b3

mentioned in commit ansible/roles/heartbeat@d13b25b7

mentioned in commit ansible/plugins/fluentd@6a936199

mentioned in commit ansible/roles/discourse@8de86c44

mentioned in commit ansible/roles/spideroak@22a14ba8

mentioned in commit ansible/roles/nextcloud@75c46d32

mentioned in commit ansible/roles/keycloak@0a0c58ee

mentioned in commit ansible/roles/fail2ban@1241bd18

mentioned in commit ansible/roles/composer@5226478e

mentioned in commit ansible/roles/jailkit@878d8ef7

mentioned in commit ansible/roles/haproxy@bc845488

mentioned in commit ansible/roles/fluentd@07cfc883

mentioned in commit ansible/roles/zammad@6e4f1031

mentioned in commit ansible/roles/apache@7c08b591

mentioned in commit ansible/roles/oracle@12bcccaa

mentioned in commit ansible/roles/gitlab@1b8642e6

mentioned in commit ansible/roles/mysql@90f398d3

mentioned in commit ansible/roles/vpn@44eb6198

mentioned in commit ansible/roles/php@1ce68bae

mentioned in commit ansible/playbooks/general@bf23639b

Basic structure is completed, automatic deployment is implemented and Ansible content completely moved over. Next, we should get together and coordinate our effort on how to move over other existing content and how we want to structure the content on the new site. Let's chat about a possible Zoom meeting on Mattermost.

moved from docker/l3d#74 (moved)

Items to think about regarding the structure:

• each project in GitLab should have at least one page in the docs
• the link to the documentation could be added to the project description in GitLab, instead of a short readme in the project
• we don't use wikis in GitLab anymore
• what about private repositories for customers: continue with wiki or setup their own mkdocs instance with access control
• the structure of each section on mkdocs should be clearly defined so that we use the same everywhere, makes it easier to use then - let's have a look into metadata directly in the md files
• what about changelog: maintain that in the docs or in the repo
• each docs page should link directly to the repo and the issue queue
• Should we use tagging? See https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#tags
• Should we document helpful console commands?

mentioned in commit cc89352f

The guidelines have been added to the documentation and there is a link on the front page to them. They cover all decisions we've made for each item in the list above, except these:

• Private customer projects: that's not urgent just now, and we want to get familiar with the tool first before we decide on how we can improve customer projects
• Console commands: yes, let add them to their own section

By that, we can now close this issue and keep going with individual tasks.

closed