[GSoC2023] Upgrade the documentation system
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Re: [GSoC2023] Upgrade the documentation system
I'm very excited to see how this project goes: I am quite fond of Markdown, and I'm very frustrated by the poor search (particularly as it relates to translation) of the current wiki. I've looked a little bit at Docusaurus (which I think you have also seen) and it seemed to hold great promise. I hope you can find a good way to make a seamless transition from the existing documentation to a nicer platform. My understanding of the wiki translation is that it's totally self-contained, right? There's nothing being done on CrowdIn?
Re: [GSoC2023] Upgrade the documentation system
That's right. And of course that's one of the problems. We never know until when our MediaWiki translation plugin will work...
That's very interesting. The git bla-bla is completely hidden from the user, and there is a sidebar with the page contents. I just tried setting one up too for https://github.com/yorikvanhavre/FreeCAD-NativeIFC . What I like most is that it's basically zero maintenance and platform dependency and extremely portable. I'd be curious to see if it can be ported "as is" to, for example, gitlab or gitea-based platforms like codeberg.org.gauriimaheshwarii wrote: ↑Sun May 21, 2023 7:28 pm Set up a Wiki in the same repository as a sandbox project to allow the FreeCAD contributors to play around with the documentation and get familiar with the platform.
Re: [GSoC2023] Upgrade the documentation system
Some things that I found out about github wikis:
- You don't use the .md suffix in links.
- You can put files in subfolders, it stays so in the git structure, but you don't use subfolders in links. Ex: a link to subfolder/mypage lokks like this: [my page](mypage)
- We can give wiki write access either to anybody with a github account, or only to collaborators of the FreeCAD repo. This might be annoying as there is no fine-tuning possible (we would want not everybody to be able to write, but also not only people with write permission to the FreeCAD repo)
- The wiki editing interface is the same as the normal markdown edit UI of github. So for editors there is not much advantage in using a wiki over a standard repo
Here is an example of a translated github wiki. Not sure how it was done, though: https://github.com/JustArchiNET/ArchiSteamFarm/wiki
- You don't use the .md suffix in links.
- You can put files in subfolders, it stays so in the git structure, but you don't use subfolders in links. Ex: a link to subfolder/mypage lokks like this: [my page](mypage)
- We can give wiki write access either to anybody with a github account, or only to collaborators of the FreeCAD repo. This might be annoying as there is no fine-tuning possible (we would want not everybody to be able to write, but also not only people with write permission to the FreeCAD repo)
- The wiki editing interface is the same as the normal markdown edit UI of github. So for editors there is not much advantage in using a wiki over a standard repo
Here is an example of a translated github wiki. Not sure how it was done, though: https://github.com/JustArchiNET/ArchiSteamFarm/wiki
-
- Posts: 11
- Joined: Sun Feb 26, 2023 12:54 pm
- Location: New Delhi, India
- Contact:
Re: [GSoC2023] Upgrade the documentation system
- May 25, 2023 -
The Docusaurus website is currently available locally on my system. Attaching link to the screenshots here to show how the 'Getting Started' page looks.
Docusaurus allows viewing in both light and dark modes, and when clicked on 'Edit this page', it redirects to the GitHub repository where the file is located.
Kindly ignore the Tutorial Intro, Basics, and Extras sections on the left and the Blog section on the top.
Your reviews and suggestions are welcome :)
- Tried making the Getting started page in Markdown on GitHub Wiki and Docusaurus.
The Docusaurus website is currently available locally on my system. Attaching link to the screenshots here to show how the 'Getting Started' page looks.
Docusaurus allows viewing in both light and dark modes, and when clicked on 'Edit this page', it redirects to the GitHub repository where the file is located.
Kindly ignore the Tutorial Intro, Basics, and Extras sections on the left and the Blog section on the top.
Your reviews and suggestions are welcome :)
Last edited by gauriimaheshwarii on Fri May 26, 2023 4:40 am, edited 1 time in total.
- adrianinsaval
- Veteran
- Posts: 5541
- Joined: Thu Apr 05, 2018 5:15 pm
Re: [GSoC2023] Upgrade the documentation system
how do you edit the wiki when using that? does it need to be through a PR on github?
Re: [GSoC2023] Upgrade the documentation system
That's nice!
There is a demo version of docusaurus here: https://docusaurus.io/docs/playground
It has also built-in support for crowdin, that's a huge plus.
I would like to see how the git repo associated with a docusaurus site looks like... If it is "portable" enough, that might be a very good solution.
Regarding PRs, if the documentation was on its own repo, we could do even better than on the current wiki: Trusted wiki editors have write permission, and can edit the doc directly, same as they currently do on the wiki, and occasional editors would go through PRs.
There is a demo version of docusaurus here: https://docusaurus.io/docs/playground
It has also built-in support for crowdin, that's a huge plus.
I would like to see how the git repo associated with a docusaurus site looks like... If it is "portable" enough, that might be a very good solution.
Regarding PRs, if the documentation was on its own repo, we could do even better than on the current wiki: Trusted wiki editors have write permission, and can edit the doc directly, same as they currently do on the wiki, and occasional editors would go through PRs.
-
- Posts: 11
- Joined: Sun Feb 26, 2023 12:54 pm
- Location: New Delhi, India
- Contact:
Re: [GSoC2023] Upgrade the documentation system
Only the collaborators can edit the GitHub wiki. Occasional editors will have to raise a PR.adrianinsaval wrote: ↑Thu May 25, 2023 8:23 pm how do you edit the wiki when using that? does it need to be through a PR on github?
I am still fixing the git repo, was facing some trouble while deploying the website.
Will share an update by Sunday.
Re: [GSoC2023] Upgrade the documentation system
Hi
bienvenue au club
mario
+1gauriimaheshwarii wrote: ↑Sun May 21, 2023 7:28 pm I thought why not post regular updates of my work here only.
bienvenue au club
mario
Maybe you need a special feature, go into Macros_recipes and Code_snippets, Topological_data_scripting.
My macros on Gist.github here complete macros Wiki and forum.
My macros on Gist.github here complete macros Wiki and forum.
-
- Posts: 11
- Joined: Sun Feb 26, 2023 12:54 pm
- Location: New Delhi, India
- Contact:
Re: [GSoC2023] Upgrade the documentation system
Hello everyone!
The project I am working on is upgrading the documentation system of FreeCAD with my mentor @kkremitzki.
For the new documentation of the software, we decided to go with Docusaurus because of several reasons, including the fact that it is git-based and open-source.
Till now, we have worked on the structure of the website, and have defined a layout for it. The first pages of each section and sub-section are made in a new way, though the linked pages still redirect to the current wiki. We are still working on the same, as every page is made manually and there are over a thousand files.
The website is viewable in both light and dark modes.
We are also looking at the possible ways to support multiple languages for the users.
There is still an issue of image sizes to be tackled.
Also, kindly ignore the tutorial tabs on the sidebar.
Reviews from the community are crucial for this project. Here is the link to the work we have done until now.
https://documentation-freecad-docusauru ... docs/intro
Your reviews, suggestions, and ideas are welcome. Please let us know what you think so that we can improve and make it better
You can find the entire code here.
The project I am working on is upgrading the documentation system of FreeCAD with my mentor @kkremitzki.
For the new documentation of the software, we decided to go with Docusaurus because of several reasons, including the fact that it is git-based and open-source.
Till now, we have worked on the structure of the website, and have defined a layout for it. The first pages of each section and sub-section are made in a new way, though the linked pages still redirect to the current wiki. We are still working on the same, as every page is made manually and there are over a thousand files.
The website is viewable in both light and dark modes.
We are also looking at the possible ways to support multiple languages for the users.
There is still an issue of image sizes to be tackled.
Also, kindly ignore the tutorial tabs on the sidebar.
Reviews from the community are crucial for this project. Here is the link to the work we have done until now.
https://documentation-freecad-docusauru ... docs/intro
Your reviews, suggestions, and ideas are welcome. Please let us know what you think so that we can improve and make it better
You can find the entire code here.
Last edited by gauriimaheshwarii on Sun Jul 16, 2023 7:23 pm, edited 1 time in total.
Re: [GSoC2023] Upgrade the documentation system
It looks very pleasant. Congrats on your first achievements.
I will be looking forward to information for the translators of the documentation.
ps
As of the middle of last month, the wiki had 1,860 pages that can be translated, There are also a few without translation capabilities.
Twórca polskiej wersji Wiki dla FreeCAD, współwórca polskiej wersji GUI.
"Cierpliwym być musisz, by wiedzę zgłębiać tajemną, gdyż ciemna strona mocy niszczącą i silną jest".
"Cierpliwym być musisz, by wiedzę zgłębiać tajemną, gdyż ciemna strona mocy niszczącą i silną jest".