-
Notifications
You must be signed in to change notification settings - Fork 330
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
Add MKdocs for Friendica doc #11702
base: develop
Are you sure you want to change the base?
Add MKdocs for Friendica doc #11702
Conversation
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 |
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. |
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: Theming (fonts, colors,...) Are changeable too, even multitheming is supported :) |
Thanks for taking action on this based on the recent discussion. 2 Cents: personal preference for |
Thank you! Do you see any advantages for 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 |
Updates :-) Changes:
|
Please have in mind that the database structure files are created automatically via this function: friendica/src/Database/DBStructure.php Line 163 in e6ed8f6
|
Yes, it's possible to have language agnostic files, so I guess it shouldn't be a problem :) |
My comment was meant as a hint that you please change the paths in that function as well 😬 |
Yes got it 😊 |
@annando the index, db-structure and navigation is now automatically created, have a look at: https://doc-test.philipp.info/spec/database/ my adapted |
I just had a thought: Possibly we can automatically generate the API documentation from the router definition? |
I like your thought!! :D |
If overhead is increased using ReadTheDocs theme, lets go with the theme that causes less work. |
df38d26
to
96f263f
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
@nupplaphil I would recommend a |
1983146
to
302acc2
Compare
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.. |
Please rebase on the latest develop given the forecasted conflicts. |
@@ -0,0 +1,264 @@ | |||
#### DON'T EDIT THIS FILE AT ROOT, use /view/templates/mkdocs.yaml.tpl Template #### |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This file has been moved since
#### 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 #### |
@@ -0,0 +1,191 @@ | |||
#### DON'T EDIT THIS FILE AT ROOT, use /view/templates/mkdocs.yaml.tpl Template #### |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
#### 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 #### |
@nupplaphil Do you mind me asking why you closed this PR? |
Personally had high hopes for this to resolve the clusterjoy the friendica wiki currently is. What is the alternative route forward? |
It was by accident, thx for mentioning it :-) |
In case this PR shall be part of the 2023.09 (10) release, please redirect it towards the 2023.09-rc branch. |
And now it's full of conflicts, do you need help rebasing this, @nupplaphil ? |
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. |
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:
/help
DBStructure
methods because of new paths (thx @annando )