[GSoC2023] Upgrade the documentation system

Contributions from the participants, questions and answers to their projects.
Discussions of proposals for upcoming events.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
chennes
Veteran
Posts: 3881
Joined: Fri Dec 23, 2016 3:38 pm
Location: Norman, OK, USA
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by chennes »

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?
Chris Hennes
Pioneer Library System
GitHub profile, LinkedIn profile, chrishennes.com
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by yorik »

chennes wrote: Sun May 21, 2023 9:06 pm My understanding of the wiki translation is that it's totally self-contained, right? There's nothing being done on CrowdIn?
That's right. And of course that's one of the problems. We never know until when our MediaWiki translation plugin will work...
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.
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.
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by yorik »

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
gauriimaheshwarii
Posts: 11
Joined: Sun Feb 26, 2023 12:54 pm
Location: New Delhi, India
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by gauriimaheshwarii »

- May 25, 2023 -
  • Tried making the Getting started page in Markdown on GitHub Wiki and Docusaurus.
Check out the Wiki page here.
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.
User avatar
adrianinsaval
Veteran
Posts: 5541
Joined: Thu Apr 05, 2018 5:15 pm

Re: [GSoC2023] Upgrade the documentation system

Post by adrianinsaval »

how do you edit the wiki when using that? does it need to be through a PR on github?
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by yorik »

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.
gauriimaheshwarii
Posts: 11
Joined: Sun Feb 26, 2023 12:54 pm
Location: New Delhi, India
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by gauriimaheshwarii »

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?
Only the collaborators can edit the GitHub wiki. Occasional editors will have to raise a PR.
yorik wrote: Fri May 26, 2023 9:03 am 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.
I am still fixing the git repo, was facing some trouble while deploying the website.
Will share an update by Sunday.
mario52
Veteran
Posts: 4673
Joined: Wed May 16, 2012 2:13 pm

Re: [GSoC2023] Upgrade the documentation system

Post by mario52 »

Hi
gauriimaheshwarii wrote: Sun May 21, 2023 7:28 pm I thought why not post regular updates of my work here only.
+1

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.
gauriimaheshwarii
Posts: 11
Joined: Sun Feb 26, 2023 12:54 pm
Location: New Delhi, India
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by gauriimaheshwarii »

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.
Last edited by gauriimaheshwarii on Sun Jul 16, 2023 7:23 pm, edited 1 time in total.
User avatar
kaktus
Veteran
Posts: 1174
Joined: Sun Aug 11, 2019 11:59 am
Location: opolskie
Contact:

Re: [GSoC2023] Upgrade the documentation system

Post by kaktus »

:mrgreen:
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".
Post Reply