Developer guides – Documentation & Wiki

This page aims to give a quick overview about the style and structure of this Wiki and documentation of the project in general.

• Proper documentation
• Docstrings
• Page naming
• Sidebar

Proper documentation

Documentation is an integral part of every project - the same is true for ours. With the initial part of development complete, where features were added, updated and removed on a weekly basis, proper and thorough documentation of the various parts of the framework should be a priority. This is especially true for those parts of the framework that will probably be updated the most: the logic behind how our marketplaces work, including customer and owner logic.

So take this first section as the kind request to keep those parts of the wiki updated - if they are out-of-date, the information they contain may do more harm than help in understanding the framework.

Docstrings

Within the code itself, we use docstrings to add interface descriptions to our classes and functions, as well as offer short descriptions of the respective function's purpose and use. The docstring coverage is being monitored through the interrogate tool, which is automatically run before each commit through the pre-commit tool, as well as during the Github CI pipeline.

Within the pre-commit-config.yaml file, developers can set a threshold for the percentage of classes and functions that must have a docstring, under which the tool will fail and the commit be rejected.

Page naming

Many of the pages in this wiki are subpages of another page, i.e. they belong to a category. For example, this documentation & wiki page is a subpage of the developer guides category.

While we are using a custom sidebar to represent this ordering nicely, we also want the pages to be ordered correctly in the default Pages view of the Github wiki. In this view, all pages are ordered alphabetically by default. To group pages which belong together, we thereby prepend the category name of a page to its name, in the following format:

Category name – Subpage name

Please not that the separator is a long dash (–), not a -. This needs to be done as all wiki pages are represented as .md files by Github. The filenames of those files use - as a separator instead of a space, which makes it impossible to use a - in the name of a page.

Similarly, there are a number of characters which are not forbidden, but should be avoided when naming pages, as they make the filenames invalid on some operating systems. For this reason, the long dash – was chosen as a separator. An exemplary filename could be as follows:

Developer-guides-–-Documentation-&-Wiki.md

For better structuring of the wiki, pages belonging to the same category are grouped within folders in the internal representation of the wiki. This grouping is only visible when cloning the wiki locally, and any new page created through the Github interface will be placed at the root directory. We therefore ask contributors to clone the wiki locally when adding new pages. Also note that when linking to other pages in the wiki, it is not necessary to provide the whole path, but only the filename. You can also orient yourself on the various internal links contained in this page.

Sidebar

You may have noticed that this wiki features a custom sidebar to the right of the page. This was done to allow us to group the different categories together nicer than the default sidebar would (which you can still view by expanding the Pages menu at the top right).

The sidebar logic is implemented in the _Sidebar.md file, which can be modified either by directly editing the file after cloning the wiki locally, or by accessing this page.

The sidebar must only be updated if a new page is added to the wiki, or an existing page is renamed or moved. You can orient yourself with the current implementation and simply mirror it.