From 4a3fe9cf9989ac4b66dd628b1d4bb0c480d27abd Mon Sep 17 00:00:00 2001 From: Pieter Hijma Date: Thu, 27 Mar 2025 16:37:18 +0100 Subject: [PATCH] [Doc] Improve the main page for WebDoc For the web version, the main page has improved with more information about the organization with respect to the topics. The most important topics are listed prominently on the main page as well. --- src/Doc/mainpage.dox.in | 126 +++++++++++++++++++++++++++------------- 1 file changed, 87 insertions(+), 39 deletions(-) diff --git a/src/Doc/mainpage.dox.in b/src/Doc/mainpage.dox.in index 5ab0e6c5dc..d3803f155f 100644 --- a/src/Doc/mainpage.dox.in +++ b/src/Doc/mainpage.dox.in @@ -22,64 +22,112 @@ /** - \mainpage FreeCAD source documentation + @mainpage FreeCAD Source Documentation - This is the source documentation of FreeCAD. - It is automatically generated from the source code, and describes the different - components of the FreeCAD source code, for both the parts written in C++ and Python. - - For general help and documentation about the FreeCAD application and how to use it, head - first to the Wiki Documentation. - - Refer to the - general - introduction to the FreeCAD source code page for a broad view of how the source - code is organized, and browse the modules, classes and namespaces from the menu above. - - The Developers section - of the wiki also contains additional information for developers, and the - Powerusers / python scripting - section contains coding documentation that is specifically aimed at python scripting, but - that will also be useful to C++ coders, as most of the APIs are identical or very similar. - - For space reasons, this on-line version doesn't include the source code headers nor the full - inheritance graphics. But you can build a full version yourself with everything included, - as explained in building - the source code documentation. You can also browse through the source - code on github. + @section toc Table of Contents + - @ref intro_main "Introduction" + - @ref organization "Organization of the API Documentation" + - @ref other_doc "Other Documentation" - \if DEV_DOCUMENTATION + @section intro_main Introduction - \mainpage FreeCAD source documentation + This is the source documentation of [FreeCAD](https://www.freecad.org). It + is automatically generated from the source code and describes the different + components of the FreeCAD source code, for both the parts written in C++ + and Python. The next section discusses the organization of this API + documentation and the last section describes other forms of documentation + that FreeCAD has. + + @section organization Organization of the API Documentation + + This documentation is divided into several topics of which the most important are: + - @ref CORE "Core" + - @ref BASE "Base" + - @ref APP "App" + - @ref GUI "Gui" + - @ref WORKBENCHES "Workbenches" + - @ref EMBEDDED "Embedded 3rd party packages" + + Firstly, topic @ref CORE "Core" contains the core namespaces and classes + that all of FreeCAD relies on. This consists of namespace %Base (see topic + @ref BASE "Base") that contains fundamental base classes, the namespace + %App (see topic @ref APP "App") that contains classes for FreeCAD in + command-line mode, and namespace %Gui (see topic @ref GUI "Gui") that + contains the classes for FreeCAD's GUI. + + FreeCAD is highly modular and most of its functionality is within modules + that are called @ref WORKBENCHES "Workbenches". Workbenches can be written + in C++ or Python or in a combination of the two. FreeCAD also has external + workbenches that can be loaded from the Addon Manager. These external + workbenches need to be written in Python. + + Finally, there is the topic @ref EMBEDDED "Embedded 3rd party packages" + that contains 3rd-party software of which the source is embedded in + FreeCAD. This means that during compilation, these packages will be + compiled and linked to FreeCAD as opposed to non-embedded 3rd-party + packages that are only linked to FreeCAD. An example of an important + non-embedded 3rd party software package is [Open CASCADE + Technology](https://dev.opencascade.org/doc/overview/html/). Its API + documentation can be found + [here](https://dev.opencascade.org/doc/refman/html/index.html). + + @section other_doc Other Documentation + + For general help and documentation about the FreeCAD application and how to + use it, head first to the [Wiki Documentation](https://www.freecad.org/wiki). + + Refer to the [Wiki page "The FreeCAD source + code"](https://www.freecad.org/wiki/The_FreeCAD_source_code) for a broad + view of how the source code is organized, and browse the modules, classes + and namespaces from the menu above. + + The [Developer hub](https://www.freecad.org/wiki/Developer_hub) of the wiki + contains additional information for developers and the [Power users / + Python scripting section](https://www.freecad.org/wiki/Power_users_hub) + contains coding documentation that is specifically aimed at Python + scripting, but that will also be useful to C++ coders, as most of the APIs + are identical or very similar. + + For space reasons, this on-line version doesn't include the source code + headers nor the full inheritance graphics. But you can build a full version + yourself with everything included, as explained in Wiki page [Source + documentation](https://wiki.freecad.org/Source_documentation#Complete_documentation). You + can also browse through the [source code on + GitHub](https://github.com/FreeCAD/FreeCAD). + + @if DEV_DOCUMENTATION + + @mainpage FreeCAD source documentation + + @image html freecadsplash.png - \image html freecadsplash.png - Welcome to FreeCAD source documentation! - + We hope you'll find it a convenient tool to explore, understand and experiment with the internals of the program. - + Being generated from the actual state of the code, this documentation is by no means a well structured corpus or a textbook, but more an utility to browse through the sources. - + If you seek information on FreeCAD at large, please consult our Wiki - + FreeCAD being a fast moving target, don't hesitate to rebuild an up to date doc from source as often as needed (\ref makingdocs "more info"). CPU cycles are cheap - nowadays! - + nowadays! + The homepage of FreeCAD is here. - - \endif + + @endif @GIT_REVISION_INFO@ */ -/** \namespace std - \brief The Standard namespace for the C++ library -*/ +/** + * @namespace std + * @brief The Standard namespace for the C++ library + */