diff --git a/Manifest.md b/Manifest.md index db6e96232a..dba1b33fab 100644 --- a/Manifest.md +++ b/Manifest.md @@ -1,10 +1,10 @@ -# FreeCAD documentation rewrite +# FreeCAD documentation rewrite #### Problem -The current documentation system is built with [Qt Assistant](https://doc.qt.io/qt-5/assistant-quick-guide.html). It consists of a large set of HTML files obtained by scraping and converting pages from the [FreeCAD wiki](https://wiki.freecadweb.org) 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: +The current documentation system is built with [Qt Assistant](https://doc.qt.io/qt-5/assistant-quick-guide.html). It consists of a large set of HTML files obtained by scraping and converting pages from the [FreeCAD Wiki][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 @@ -35,3 +35,5 @@ A system that stops using Qt Assistant, allows people to still use the wiki (for * 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) + +[Wiki]: https://wiki.freecad.org \ No newline at end of file diff --git a/README.md b/README.md index dfe964b822..c03e1ed3b7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # The FreeCAD documentation -**Note**: This repository contains an automatic conversion of the FreeCAD wiki located at https://wiki.freecadweb.org to the [markdown format](https://en.wikipedia.org/wiki/Markdown). The conversion is done automatically through the [migrate.py](./migrate.py) script located within this repository. The script downloads the wiki contents in XML format using the MediaWiki API and uses [pandoc](https://pandoc.org/) to convert between MediaWiki and markdown formats. This is a work in progress towards a more usable and portable version of the documentation, to be used from within FreeCAD through the [Help module](https://github.com/yorikvanhavre/FreeCAD-Help). +**Note**: This repository contains an automatic conversion of the [FreeCAD Wiki][Wiki] to the [markdown format](https://en.wikipedia.org/wiki/Markdown). The conversion is done automatically through the [migrate.py](./migrate.py) script located within this repository. The script downloads the wiki contents in XML format using the MediaWiki API and uses [pandoc](https://pandoc.org/) to convert between MediaWiki and markdown formats. This is a work in progress towards a more usable and portable version of the documentation, to be used from within FreeCAD through the [Help module](https://github.com/yorikvanhavre/FreeCAD-Help). This documentation can be installed via the FreeCAD [addons manager](wiki/Std_AddonMgr.md) for offline browsing. @@ -8,7 +8,7 @@ This documentation can be installed via the FreeCAD [addons manager](wiki/Std_Ad ## Introduction -This is the official documentation of [FreeCAD](http://www.freecadweb.org). There are several ways to use this documentation: by exploring the **hubs**, by following the **manual**, or by **searching** for a specific page. The **Help menu** entries from within FreeCAD also allow you to browse this documentation, online or offline. This documentation is a work in progress, written by the community of users and developers of FreeCAD. If you find information that is wrong or missing, please [help](Special:MyLanguage/help_FreeCAD.md)! +This is the official documentation of [FreeCAD]. There are several ways to use this documentation: by exploring the **hubs**, by following the **manual**, or by **searching** for a specific page. The **Help menu** entries from within FreeCAD also allow you to browse this documentation, online or offline. This documentation is a work in progress, written by the community of users and developers of FreeCAD. If you find information that is wrong or missing, please [help](Special:MyLanguage/help_FreeCAD.md)! @@ -39,7 +39,7 @@ This section contains material for developers who want to work with the C++/Pyth #### [The FreeCAD manual](wiki/Manual_Introduction.md) -The manual is another, more linear way to present the information contained in this wiki. It is designed to be read like a book, and will gently introduce you to many other pages from the hubs above. [ebook versions](https://www.gitbook.com/book/yorikvanhavre/a-freecad-manual/details) are also available, as well as [a couple of translations in pdf format](https://www.freecadweb.org/manual/). +The manual is another, more linear way to present the information contained in this wiki. It is designed to be read like a book, and will gently introduce you to many other pages from the hubs above. [ebook versions](https://www.gitbook.com/book/yorikvanhavre/a-freecad-manual/details) are also available, as well as [a couple of translations in pdf format][Manual]. @@ -64,5 +64,10 @@ This documentation is fully translatable by users to other languages, and is in * [Help FreeCAD](wiki/Help_FreeCAD.md): How to contribute to the project? * [Donation](wiki/Donate.md) options * FreeCAD participates to the [Google Summer of Code](wiki/Google_Summer_of_Code.md) since 2016. Learn how to participate -* All the development communication happens on the [forum](http://forum.freecadweb.org), so be sure to visit it if you are interested in participating. +* All the development communication happens on the [Forum], so be sure to visit it if you are interested in participating. + +[FreeCAD]: https://freecad.org +[Manual]: https://freecad.org/manual +[Forum]: https://forum.freecad.org +[Wiki]: https://wiki.freecad.org \ No newline at end of file diff --git a/TODO.md b/TODO.md index e9c0a39b27..77c4764ae6 100644 --- a/TODO.md +++ b/TODO.md @@ -1,6 +1,6 @@ # FreeCAD documentation -This repository contains an automatic conversion of the FreeCAD wiki located at https://wiki.freecadweb.org to [markdown format](https://en.wikipedia.org/wiki/Markdown). The conversion is done automatically through the [migrate.py](./migrate.py) script located within this repository. The script downloads the wiki contents in XML format using the MediaWiki API and uses [pandoc](https://pandoc.org/) to convert between mediawiki and markdown formats. +This repository contains an automatic conversion of the [FreeCAD Wiki][Wiki] to [markdown format](https://en.wikipedia.org/wiki/Markdown). The conversion is done automatically through the [migrate.py](./migrate.py) script located within this repository. The script downloads the wiki contents in XML format using the MediaWiki API and uses [pandoc](https://pandoc.org/) to convert between mediawiki and markdown formats. The general idea is to keep allowing users to use the wiki to edit and add contents, while the markdown format for: @@ -21,3 +21,5 @@ Further goals: * Tie the FreeCAD what's this system to the Help workbench * Allow to export parts of the documentation to other formats (PDF, ePub,...) + +[Wiki]: https://wiki.freecad.org \ No newline at end of file diff --git a/migrate.py b/migrate.py index b0ed73ca6a..dc56190c49 100755 --- a/migrate.py +++ b/migrate.py @@ -78,7 +78,7 @@ import inspect unhandledTemplates = [] # holder for unhandled templates -BASE_URL = "https://wiki.freecadweb.org" +BASE_URL = "https://wiki.freecad.org" THREADS = 8 # number of threads for file writing WIKIFOLDER = "wiki" CATEGORY_COLUMNS = 3 # the number of columns on category pages @@ -96,7 +96,7 @@ class MediaWiki: """MediaWiki([url]) - A class to represent an online MediaWiki instance. - default url is wiki.freecadweb.org""" + default url is wiki.freecad.org""" def __init__(self,url=BASE_URL):