Hello,
I thought I would give the akkoma-docs a slight overhaul in hopes they are even more useful and easier to maintain in the long run. Since I am not 100% sure on certain things I thought that it might be a good idea to post here first and grab some feedback.
I noticed some stuff that needed fixing in the docs so I looked more closely at them to hopefully optimize them a bit, make them clearer and make maintenance a bit easier as well. I will be concentrating on the installation bits for now.
First thing I noticed was that the installation bit could use some better sorting. As it is right now mkdocs just throws all the pages into alphabetical order, which isn’t really ideal, see here on the left bar: https://docs.akkoma.dev/develop/installation/alpine_linux_en/
I found a nice plugin for mkdocs called mkdocs awesome pages plugin, which should help a bit with sorting while still being somewhat easy to maintain.
I moved some stuff into folders and added a .pages-file, which is used to sort the folders however you want with the mkdocs awesome pages plugin.
I then noticed that some blocks of documentation are repeated throughout the different distros, so I moved some stuff to include-files in the includes-folder. Since arch, debian and fedora used some of the same explanations, those are now centralized in these include files.
I did not really touch docker, the BSDs, Alpine (since it uses doas instead of sudo) or Gentoo (cause its gentoo really). So there still might be more common blocks that one could put into an include-file as well.
Since I created a lot of folders in the docs I had to go around and fix quite a few links, but they should work now (mkdocs is fairly neat since it warns you about broken links when serving the site!)
As for sorting things I opted to go
- OTP
- Source
- Docker
- Migration
- Optional
I think it should* be a good idea to list OTP first, since I guess this should be the main mode of deployment for this software. If you have a better idea for sorting this let me know! Inside the folders its then just sorted alphabetical again.
I also fixed up the build dependencies to include the plugin used, so it should work. Though after I moved the include-files into the “includes” folder I still get some errors from mkdocs serve:
output of: mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
Warning: could not find file docs/installation/frontends.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/frontends.include'
Warning: could not find file docs/installation/further_reading.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/further_reading.include'
Warning: could not find file docs/installation/otp_vs_from_source.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/otp_vs_from_source.include'
Warning: could not find file docs/installation/frontends.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/frontends.include'
Warning: could not find file docs/installation/further_reading.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/further_reading.include'
Warning: could not find file docs/installation/otp_vs_from_source_source.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/otp_vs_from_source_source.include'
Warning: could not find file docs/installation/generic_dependencies.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/generic_dependencies.include'
Warning: could not find file docs/installation/otp_vs_from_source_source.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/otp_vs_from_source_source.include'
Warning: could not find file docs/installation/otp_vs_from_source_source.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/otp_vs_from_source_source.include'
Warning: could not find file docs/installation/generic_dependencies.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/generic_dependencies.include'
Warning: could not find file docs/installation/generic_dependencies.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/generic_dependencies.include'
Warning: could not find file docs/installation/generic_dependencies.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/generic_dependencies.include'
Warning: could not find file docs/installation/frontends.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/frontends.include'
Warning: could not find file docs/installation/otp_vs_from_source_source.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/otp_vs_from_source_source.include'
Warning: could not find file docs/installation/generic_dependencies.include. Ignoring include statement. Error: [Errno 2] No such file or directory: 'docs/installation/generic_dependencies.include'
INFO - Documentation built in 2.06 seconds
INFO - [12:56:13] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [12:56:13] Serving on http://127.0.0.1:8000/
I guess the include-location is hardcoded somewhere and thats why it throws these errors? I could not find anything really. It seems to build the docs fine since they look fine in my test-deployment above.
is there something I missed or something else that might need some cleanup? Feedback is welcome!
Second Post will contain 2 more links since discourse only allows two links for new users (yay spam-protection!)