Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor: Merge user, admin and developer documentation #1107

Merged
merged 2 commits into from
Oct 20, 2023
Merged

Conversation

MoritzWeber0
Copy link
Member

Previously, we had four different types of documentation:

  • Developer documentation (exposed via Github pages)
  • User documentation (exposed via individual instances)
  • Admin documentation (partially in user docs, partially in README/CONRIBUTING)
  • Getting started (in Github repository)

The number of different documentations led to increased maintainance effort. Also, there was no single source of truth.

In this commit, all four documentation types are merged into one mkdocs documentation. The documentation lived in the docs directory. Switching between the different documentation types is now done via navigation tabs. The new documentation is exposed via Github pages, making the user documentation also available when no instance is running.

In addition to the merge, there were some other small changes:

  • A new Makefile in the docs directory is added.
  • The documentation is now part of the dev target in the Makefile. Run it via make -j4 dev.
  • The code style development documentation was splitted into different backend and frontend code style pages.
  • Most of the information in the CONTRIBUTING.md is moved to the development documentation.
  • The development setup guide was simplified and and the focus is on getting everything running at the same time, not each service individually. All optional configuration options are moved to other parts of the documentation.
  • The uninstall guide of the README.md is moved to the admin docs.
  • A custom style.css is added to always show a scroll bar. It prevents vertical jumping when the scroll bar appears.

@MoritzWeber0 MoritzWeber0 marked this pull request as draft October 18, 2023 10:31
@codecov
Copy link

codecov bot commented Oct 18, 2023

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (3feca10) 71.64% compared to head (0795abc) 71.64%.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1107   +/-   ##
=======================================
  Coverage   71.64%   71.64%           
=======================================
  Files         160      160           
  Lines        5078     5078           
  Branches      544      544           
=======================================
  Hits         3638     3638           
  Misses       1336     1336           
  Partials      104      104           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@MoritzWeber0 MoritzWeber0 force-pushed the merge-docs branch 3 times, most recently from c865a83 to 1d5ab4c Compare October 18, 2023 11:12
@MoritzWeber0 MoritzWeber0 marked this pull request as ready for review October 18, 2023 12:00
@MoritzWeber0 MoritzWeber0 requested review from dominik003, amolenaar and Paula-Kli and removed request for dominik003 October 18, 2023 12:01
Copy link
Contributor

@amolenaar amolenaar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. I found a few improvements.

Also updated the Makefile, since the docs container could no longer be built.

docs/docs/admin/index.md Outdated Show resolved Hide resolved
docs/docs/admin/index.md Outdated Show resolved Hide resolved
docs/docs/development/index.md Show resolved Hide resolved
docs/docs/development/frontend/code-style.md Show resolved Hide resolved
docs/docs/development/frontend/code-style.md Show resolved Hide resolved
MoritzWeber0 and others added 2 commits October 20, 2023 18:53
Previously, we had four different types of documentation:
- Developer documentation (exposed via Github pages)
- User documentation (exposed via individual instances)
- Admin documentation (partially in user docs, partially in README/CONRIBUTING)
- Getting started (in Github repository)

The number of different documentations led to increased maintainance effort.
Also, there was no single source of truth.

In this commit, all four documentation types are merged into one
`mkdocs` documentation. The documentation lived in the `docs` directory.
Switching between the different documentation types is now done via navigation tabs.
The new documentation is exposed via Github pages, making the user documentation
also available when no instance is running.

In addition to the merge, there were some other small changes:

- A new Makefile in the `docs` directory is added.
- The documentation is now part of the `dev` target in the Makefile.
  Run it via `make -j4 dev`.
- The code style development documentation was splitted into different
  backend and frontend code style pages.
- Most of the information in the `CONTRIBUTING.md` is moved to the
  development documentation.
- The development setup guide was simplified and and the focus is
  on getting everything running at the same time, not each service
  individually. All optional configuration options are moved to
  other parts of the documentation.
- The uninstall guide of the `README.md` is moved to the admin docs.
- A custom `style.css` is added to always show a scroll bar.
  It prevents vertical jumping when the scroll bar appears.
@MoritzWeber0 MoritzWeber0 merged commit 404b23c into main Oct 20, 2023
23 checks passed
@MoritzWeber0 MoritzWeber0 deleted the merge-docs branch October 20, 2023 16:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants