Upgrade the documentation system

This page is dedicated to the description of the Google Summer of Code 2023 project idea of upgrading the documentation system of FreeCAD.

Obsolete: This page has been moved to https://github.com/FreeCAD/FreeCAD/issues/8558

Outline

FreeCAD already possesses a vast documentation, written by its users and hosted on this very wiki. On each FreeCAD release, the contents of the wiki get packed into a offline documentation package which is bundled with FreeCAD. When using the "what's this?" feature, FreeCAD users can quickly get documentation about a specific tool

Additionally, this same documentation also has several translations, hosted on the same wiki and managed by a mediawiki plugin, and also counts on the source code structure and comments, automatically extracted by the doxygen tool, and hosted on https://www.freecadweb.org/api/

However there are several problems:

• The bundled offline doc is often incomplete, due to the difficulty (and size) to pack it all
• Over a year there are significant differences between the online and offline docs
• Translations are not available offline
• The doxygen-generated docs are in a bad state, hard to read and use and don't explain APIs clearly, and confuse C++ and python
• The wiki is hard to port and back up
• Add-ons documentation is not well integrated

Additionally, the mediawiki-based documentation is more and more problematic to maintain and back up, and we are looking at transitioning to a more easily portable and redundant system like git-based wikis.

This project proposes to remedy to the main problems by:

- allowing the user to switch between online and offline documentation, and choose between different available languages - extending and bettering the doxygen-generated documentation, with special care for the python API

• proposing a better Doxygen structure for https://www.freecadweb.org/api/ possibly with interconnection with the wiki

- working on bettering the current wiki (formatting, linking between pages, navigation, etc) - reimplement the old workbench-defined documentation system, help porting the different addons - adapt the FreeCAD start page to it - adapt the FreeCAD help menu (integrate workbenches and addons help entries) - exploring the different possibilities of git-based documentation, analyzing specially their user-friendliness and ease of edition, and possibilities of maintaining large translations easily and automatically (for ex. connecting with translation platforms) and propose migration workflows

Details

• Get familiar with FreeCAD and the contents of the wiki
• Successfully compile FreeCAD (you'll be working in C++) and the Doxygen docs
• Understand how Doxygen works and specifically how it treats C++ and Python differently
• Work on the FreeCAD C++ source code (modify the whats'this and documentation system, work on the Help menu)
• Work on the in-source code documentation
• Work on the wiki documentation
• Explore and document available open-source documentation systems

Expected Outcome

• A better documentation system inside FreeCAD
• Documentation. Like all open-source projects, it is of uttermost importance to document a lot everything you do. This allows for other people to take on and extend your work more easily.
• Proposals of migration to a better documentation system that would still keep FreeCAD users happy and eager to write and translate

Project Properties

Skills

• Programming language: C++, but understanding some Python will be necessary
• Readiness to work with documentation, reasonably good english writing skills

Difficulty

Medium

Project size

175h

Additional Information

• Potential mentors: Yorik