Add MKdocs for Friendica doc

[nupplaphil]

Because of our recent discussion, I selected a popular, small Open Source framework (https://www.mkdocs.org/) to generate a more pretty, better searchable and easy translatable output.

With the current config, which is far from ready, the output would currently look like that: https://doc-test.philipp.info/

So we could setup a https://doc.friendi.ca domain and with woodpecker, it would be easy to automatically update the docs :-)
We could even create versioned docs (develop vs. stable)

The only "disadvantage" would be that we have to rewrite the /help sub-directory of the Friendica nodes. But tbh I don't find them THAT structured and a little bit clumpy to use. So in the end, it would be possible to automatically generate the static output into a "help" sub-folder as well.

ToDos:

• Restructure current docs
• Add missing German translation skeleton files
• Add CI auto-generation
• Use generated docs for Friendica node /help
• Use generated docs for (versioned) deployment onto https://doc.friendi.ca ( pinging for help with the new domain: @annando and @utzer :)
• adapt DBStructure methods because of new paths (thx @annando )

[MrPetovan]

None of the links of https://doc-test.philipp.info/ seem to work at the moment except the tab links in the top menu. 😅

In particular, the edit link doesn't work, see how it looks: https://github.com/friendica/friendica/edit/develop/doc/en/Bugs-and-Issues.md

[Quix0r]

I guess it far from being finished. https://doc-test.philipp.info/developer/Tests/?h=test actually works here (I used the search). So I guess we have to be more patient.

[nupplaphil]

Yes sorry, it's really far from ready. That's why it's at WIP state :-)

The navbar on the left should work and the translation of these sites.

But this is a big work to do and I want to know first if you agree with it, so @annando , @tobiasd as well :-)

Concerning Translation:
Every new language can be added as a new root dir beside the existing one and as far as it has the same directory structure and name, the switch at the top will work with one additional config line :)

Theming (fonts, colors,...) Are changeable too, even multitheming is supported :)

[foss-]

Thanks for taking action on this based on the recent discussion. 2 Cents: personal preference for ReadTheDocs theme.

[nupplaphil]

Thanks for taking action on this based on the recent discussion. 2 Cents: personal preference for ReadTheDocs theme.

Thank you! Do you see any advantages for ReadTheDocs over Mkdocs with material? Because material is, as far as I can see, better integrated into Mkdocs, but there's a community edition of ReadTheDocs, but it seems there is no on-premise solution - just a basic fork for themen Mkdocs like ReadTheDocs (see https://github.com/cjsheets/mkdocs-rtd-dropdown)

So if we would choose this theme, from my point of view, there has to be some real advantages gg ..

[Edit] OK there are more features at ReadTheDocs --> https://docs.readthedocs.io/en/stable/features.html but tbh I'd like to stick at Mkdocs... But please challenge my point of view @foss- if you see problems/disatvantages

[nupplaphil]

Updates :-)

Changes:

• Navigation is almost complete
• German syntax/grammar fixes
• Added possibility for tags
• Added fixed anchor links
• New Examples:
  • https://doc-test.philipp.info/developer/addon-storage-backend/#icanconfigurestorage
  • https://doc-test.philipp.info/de/admin/install/

[annando]

Please have in mind that the database structure files are created automatically via this function:

friendica/src/Database/DBStructure.php

Line 163 in e6ed8f6

public static function writeStructure()

[nupplaphil]

Yes, it's possible to have language agnostic files, so I guess it shouldn't be a problem :)

[annando]

My comment was meant as a hint that you please change the paths in that function as well 😬

[nupplaphil]

Yes got it 😊

[nupplaphil]

@annando the index, db-structure and navigation is now automatically created, have a look at:

https://doc-test.philipp.info/spec/database/

my adapted DBStructure code is still uggly I must confess, but it's currently working :)

[annando]

I just had a thought: Possibly we can automatically generate the API documentation from the router definition?

[nupplaphil]

I like your thought!! :D

[foss-]

But please challenge my point of view @foss- if you see problems/disatvantages

If overhead is increased using ReadTheDocs theme, lets go with the theme that causes less work.

[Quix0r]

Please repeat this on all other occurrences, too! Or should I make a separate PR for this? @MrPetovan

[nupplaphil]

Please repeat this on all other occurrences, too! Or should I make a separate PR for this? @MrPetovan

Please adapt it at a separate PR .. this one is confusing/big enough :D

[Quix0r]

@nupplaphil I would recommend a git rebase upstream/develop (in case you call this repository "upstream").

[nupplaphil]

automatically built at https://docs.friendi.ca/develop .. still WIP ..

and the next pr should be a correction of content, which is out of date in some cases..

[MrPetovan]

Please rebase on the latest develop given the forecasted conflicts.

[MrPetovan]

This file has been moved since

Suggested change

	#### DON'T EDIT THIS FILE AT ROOT, use /view/templates/mkdocs.yaml.tpl Template ####
	#### DON'T EDIT THIS FILE AT ROOT, use /view/templates/doc/mkdocs.yaml.tpl Template ####

[MrPetovan]

Suggested change

	#### DON'T EDIT THIS FILE AT ROOT, use /view/templates/mkdocs.yaml.tpl Template ####
	#### DON'T EDIT THIS FILE AT ROOT, use /view/templates/doc/mkdocs.yaml.tpl Template ####

[MrPetovan]

@nupplaphil Do you mind me asking why you closed this PR?

[foss-]

Personally had high hopes for this to resolve the clusterjoy the friendica wiki currently is. What is the alternative route forward?

[nupplaphil]

It was by accident, thx for mentioning it :-)

[tobiasd]

In case this PR shall be part of the 2023.09 (10) release, please redirect it towards the 2023.09-rc branch.

[MrPetovan]

And now it's full of conflicts, do you need help rebasing this, @nupplaphil ?

[foss-]

Polite ping. This would be much needed. Popped back into my mind, since a third party developer linked https://docs.friendi.ca/develop/spec/api/mastodon/#implemented-endpoints

This is already so much more usable than the current wiki. It looks great, the way information is shown is very accessible.

I'd be glad if it was made usable and replaced the current wiki sooner than later.