doc/component_architecture.dot: Hyperlinks are added, such that when clicking on the caption/label of a package, the appropriate package descriptions are opened
other doc/component_*.dot: These were removed as they are not necessary any more. Those were small figures with coloured boxes, simplifying to associate the package description to the component diagram further up in the architecture description for the reader. This is not necessary any more as the package description has been moved to dedicated pages for each package. And the visual reference does not work any more, as the small figure would not be on the same page any more.
doc/decisions/dr-001.md is the "core" of this pull request: a decision is suggested that defines a rule on how the source code shall be structured in directories in order to match the software architecture
doc/software-architecture.md: The package descriptions have been moved to dedicated package description files (see below). Instead a list of references to the package descriptions is added. This way the package description is closer to the package definition. Also this way the package description does document the directory the package is defined in. The Doxygen command \subpage is used in order to generate a hierarchy of the pages.
*/README.md files: These are the new package descriptions. They are named README.md as this will tell the repository hosting system to render the content of the file below the directory listing. Their body is exactly the text which was before part of software-architecture.md. At the beginning of each file are Doxygen commands which support the references in the Doxygen generated documentation:
\dir .
\brief Package \ref <name>
Tells doxygen that the brief description of the current directory is "Package <name>" where <name> is a reference to the respective package page (see next bullet point). That is replaced by Doxygen during the generation of documentation with the name of the package page.
\page <name> (title)
\brief { brief description }
Begins the documentation of a page with the id <name>. Using pages to describe packages has the advantage, that pages can be structured hierarchically (see \subpage). The text following that paragraph is the detailed package description (which has been moved from software-architecture.md).
By placing the README.md into the respective package directories, the first file structure is already realized by this pull request.
Changes
doc/component_architecture.dot: Hyperlinks are added, such that when clicking on the caption/label of a package, the appropriate package descriptions are openeddoc/component_*.dot: These were removed as they are not necessary any more. Those were small figures with coloured boxes, simplifying to associate the package description to the component diagram further up in the architecture description for the reader. This is not necessary any more as the package description has been moved to dedicated pages for each package. And the visual reference does not work any more, as the small figure would not be on the same page any more.doc/decisions/dr-001.mdis the "core" of this pull request: a decision is suggested that defines a rule on how the source code shall be structured in directories in order to match the software architecturedoc/software-architecture.md: The package descriptions have been moved to dedicated package description files (see below). Instead a list of references to the package descriptions is added. This way the package description is closer to the package definition. Also this way the package description does document the directory the package is defined in. The Doxygen command\subpageis used in order to generate a hierarchy of the pages.*/README.mdfiles: These are the new package descriptions. They are namedREADME.mdas this will tell the repository hosting system to render the content of the file below the directory listing. Their body is exactly the text which was before part ofsoftware-architecture.md. At the beginning of each file are Doxygen commands which support the references in the Doxygen generated documentation:Tells doxygen that the brief description of the current directory is "Package
<name>" where<name>is a reference to the respective package page (see next bullet point). That is replaced by Doxygen during the generation of documentation with the name of the package page.Begins the documentation of a page with the id
<name>. Using pages to describe packages has the advantage, that pages can be structured hierarchically (see\subpage). The text following that paragraph is the detailed package description (which has been moved fromsoftware-architecture.md).By placing the
README.mdinto the respective package directories, the first file structure is already realized by this pull request.