Skip to content

Latest commit

 

History

History
37 lines (22 loc) · 3.91 KB

Manifest.md

File metadata and controls

37 lines (22 loc) · 3.91 KB
Raw

FreeCAD documentation rewrite

Problem

The current documentation system is built with Qt Assistant. It consists of a large set of HTML files obtained by scraping and converting pages from the FreeCAD wiki with their associated images. These files are bundled in a giant (~500 Mb) QHelp file that is bundled withing the FreeCAD source code. This causes many problems:

  • Gathering the HTML content is typically done at releases, is clunky and offers a pale, reduced and often outdated version of the wiki content
  • The 500 Mb file is too large for many git hosting platforms (such as GitHub) which forces us to do hacks such as splitting it in the source, and it causes big bloat of the Git history
  • There is only one, English version. Translated versions cannot be used with this system
  • There is no regular backup of the documentation. If the wiki server crashes, we loose a lot of precious data

The proposal

A system that stops using Qt Assistant, allows people to still use the wiki (for the time being), while preparing the path for a more modern way, based on Markdown. The system is based on two components:

  • A markdown version of the wiki, generated by a script that downloads/updates the entire contents of the wiki, using the MediaWiki API. It can be accessed online or installed locally via the Add-ons Manager.
  • A very simple [Help module], coded in Python, built in FreeCAD, is responsible for showing documentation pages, from a variety of sources such as online version, offline version, Markdown version, HTML version, English version or translated version, in a variety of ways (external browser, FreeCAD tab, viewer dialog,...)

Advantages

  • The FreeCAD documentation now consists of files, and is therefore git-manageable, like the source code itself, with all the advantages (backup/resiliency, pull requests, version tags that match FreeCAD versions, etc)
  • We can continue to use the wiki as long as it is convenient. The script that downloads, converts and updates the entire wiki can be run by anybody who can then submit pull requests. We get automatic backups of the wiki for the time being, and when the whole thing matures (specifically translation platforms), we can anytime stop using the wiki and rely only on the Markdown version.
  • Users can choose between online or offline documentation, choose a language, choose how they want it to be displayed, and much more.
  • We can remove all the Qt Help files from the sources (and even history)
  • Adapting the current help system of FreeCAD to make use of the Help module is very simple, it's just a matter of issuing a Help.show("Page Name") python command everywhere as needed (Help menu, "What's this" button,...) and as we are making it accessible to scripts, the Help system could be used in many more creative ways by developers.
  • The Help system can display pages outside the official FreeCAD documentation, so it can be used in addons as well
  • The help system is available in non-GUI mode too
  • Markdown is becoming widely universal, and is much more recognised and parsable by all kinds of applications or systems than the MediaWiki syntax. So our documentation becomes much more integratable into other systems.
  • Python API documentation can be regenerated each time, precisely tailored and tighly integrated into the documentation
  • The documentation can be much better integrated everywhere: In menus, in tooltips (for ex. tooltips could display some contents from the docs, ex. images)