Contributing
To submit a merge request, you must include the output of the unittests and/or test cases if any source file is changed.
Documentation
Documentation is vital and must be done throughout the project, not the end.
This includes examples for the use of each function.
Non-unity users
* Sphinx * Numpydocs formatting * Must comply with doctest * Must include examples * Doxygen * Must have a getting started page for each module * links to C# and Python interfaces for each function, module * DoxygenThere are three users of the codebase.
- People that will develop the foundation of the code (includes people like you).
- People that will use the interfaces and our codebase as an API.
- People that will use final products that are built with the codebase.
Each user group must be considered at each stage.
Coding standards are important, sometimes there is the ‘industry standard’ way.
This is not always in alignment with the needs of the project or with research.
It’s likely some things will be different, it should always be discussed and clarified.
It should also be in the documentation.
* Methods and xml format to use in methods * Algorithms should be documented inline with source rather than headers * Interface details should remain with headers
Table of contents
- Using TODO
- Documenting the heads of each file
- Documenting member fields
- Snippets and Code Samples
- Adding images for headers/sources, and markdown files (
.md)
/// TODO:
The head of each file should contain the following tags:
\file
Name of a file
e.g. /// \file node.h
https://www.doxygen.nl/manual/commands.html#cmdfile
\brief
A one-line description describing the contents of the file
e.g. /// \brief Header file for a node data structure, used in a graph ADT
https://www.doxygen.nl/manual/commands.html#cmdbrief
\author
The author of the file
If there are multiple authors,
you may use one \author tag for all of the authors,
or one \author tag per person/entity.
e.g. /// \author John Doe
https://www.doxygen.nl/manual/commands.html#cmdauthor
\date
This may be the date of the file's last update,
or the date the file was created -- whichever is relevant.
e.g. /// \date 06 Jun 2020
https://www.doxygen.nl/manual/commands.html#cmddate
An example of a file head would look like this:
///
/// \file node.h
/// \brief Header file for a node data structure, used in a graph ADT
///
/// \author John Doe
/// \date 06 Jun 2020
///
Other notes:
- Follow each
///with a single space, before using a tag. - Follow each tag with two tabs, then provide the description.
Here is a simple example:
struct position {
float x, y, z; ///< Cartesian coordinates x, y, and z
int id; ///< Unique identifier
};
The general format is ///< Description goes here,
notice that a single whitespace character follows ///<
and the field descriptions are in alignment with each other, using tabs.
Sometimes, this is not always possible,
but do your best to keep the formatting neat and consistent.
Step 0:
In a header file, at the line where you want the snippet to appear:
/// \snippet PATH_TO_FILE\filename.cpp SnippetName
If you would like to include line numbers for the snippet, you may use the tag
\snippet{lineno}
This is best used for directly referencing source files from within this repo,
since the line numbers that appear are the actual line numbers of the code used
for the snippet.
Step 1:
In PATH_TO_FILE\filename.cpp (where the snippet sample is),
/// [SnippetName]
std::cout << "My sample snippet" << std::endl;
/// [SnippetName]
Notice that the code is not a comment.
Step 2:
The following steps utilize the Doxygen GUI Frontend.
Load the Doxyfile from this repo into Doxygen, using the File menu.
The Doxyfile is in dhart\src\Doxyfile
Step 3:
- Navigate to the Expert tab on the left hand side.
- Under topics, click 'Input'.
- On the right side, scroll down until you see EXAMPLE_PATH.
- In the EXAMPLE_PATH section, click the folder button to reveal a file prompt.
- Within the file prompt, select the file path where the snippet resides. (
PATH_TO_FILE\filename.cpp) - Add any more directories/paths where your snippets will come from.
Snippets will now appear when you navigate to the Run tab, and click 'Run Doxygen'.
https://www.doxygen.nl/manual/commands.html#cmdcodeHere is an example for using the \code tag:
/*!
\code
// Use the '//' comment style.
std::cout << "Here is a test statement." << std::endl;
// You may indent your code sample as needed.
struct my_point {
double m_x;
double m_y;
};
\endcode
*/
Follow these steps to ensure consistency within the codebase:
0. Start an example block with /*!, then hit ENTER to go to the next line.
-
Hit TAB once, then use the
\codetag. Then, hit ENTER. -
Hit TAB twice, then begin your code example. You may indent as necessary for your example.
-
When your example is finished, hit ENTER, then BACKSPACE so that you are inline with the
\codetag. -
Use the
\endcodetag to end your example.
Then hit ENTER, then hit BACKSPACE as many times as necessary so that you are inline with/*!. -
Finally, end the example block with
*/.
- Note that any comments that occur within the sample must begin with
//, followed by a whitespace.
This procedure strikes the best compromise between:
- Making sure that comments work within a code example
- Not having to remove
//or///per line of the example
This ensures ease of viewing
for anyone reading the source code --
and also assists Doxygen with the
formatting process for the HTML export.
You may now use 'Run Doxygen' to export your documentation.
(There are no extra steps, unlike with the snippet section)
For headers/sources,
we will be using the \image tag to add images.
https://www.doxygen.nl/manual/commands.html#cmdimage
For markdown files (.md),
we will be using the markdown syntax for images.
https://www.doxygen.nl/manual/markdown.html#md_images
In dhart,
we have a subdirectory named docs.
(dhart\docs)
The Doxyfile will already be configured to have it's IMAGE_PATH
configured such that its working directory for images begins at
dhart\docs.
When we proceed to later steps, and we are to insert the path of an image file,
assume that the working directory for images begins at
dhart\docs.
For example, if a file is saved at:
dhart\docs\C++\images\spatialstructures\node\test-image_node-h.png,
you will specify the path:
C++\images\spatialstructures\node\test-image_node-h.png.
Notice that the dhart\docs portion is omitted when specifying the image,
since our Doxyfile will already its IMAGE_PATH configured to begin at dhart\docs.
Step 0:
Begin by saving copy of image_file,
which is the filename of the desired image,
into the following directory:
dhart\docs\language\img\enclosing_folder\module_name
language,
enclosing_folder,
and module_name are placeholders.
images will be a subdirectory within language.
Note:
In the dhart\docs directory,
there are three subdirectories:
for which the language placeholder applies:
- C# Documentation
- C++
- Python Docs
The contributing-guides subdirectory is for the images in this file.
For language,
be sure to choose the appropriate subdirectory
when saving your image file.
Although this particular example deals with inserting an image
into documentation for a C++ header file,
the same steps will apply for C# or Python sources.
For instance, the full filepath of node.h is
dhart\src\Cpp\spatialstructures\src\node.h
language is C++
enclosing_folder is spatialstructures
module_name is node
So, if we wanted to insert an image for any documentation
for node.h or node.cpp,
the image would be saved into the following directory:
dhart\docs\C++\images\spatialstructures\node
If directories img, enclosing_folder,
or module_name
do not already exist, you may create them.
We can now proceed to editing the file where we want to insert the desired image.
This could be a header/source file (step 1a), or a markdown file (step 1b).
Scroll down to the instructions that apply to your use case.
Step 1a:
In the header/source file where you want the image to appear,
navigate to the line of code where you want the image to appear.
We will now utilize the \image tag.
At the line where you want the image to appear,
enter the following:
/// \image html language\images\enclosing_folder\module_name\image_file
Remember this example is using placeholders;
be sure that language, enclosing_folder, module_name,
and image_file correspond to where your image is saved.
Also note that images is a subdirectory within your chosen language directory.
An example use of the \image tag would be:
/// \image html C++\images\spatialstructures\node\test-image_node-h.png
See line 42 - example use of the \image tag.
We will now move on to the Doxygen GUI frontend (Doxywizard) application.
Step 1b:
In the markdown file where you want the image to appear,
navigate to the line at which the image should be inserted.
We will now utilize the markdown syntax for images.
At the line where you want the image to appear,
enter the following:
Remember this example is using placeholders;
be sure that language, enclosing_folder, module_name,
and image_file correspond to where your image is saved.
An example use of the syntax would be:
language is C++
enclosing_folder is spatialstructures
module_name is node
image_file is test.png
This particular example is of mainpage.md, in dhart\src\Cpp
We will now move on to the Doxygen GUI frontend (Doxywizard) application.
Step 2:
Open Doxywizard.
In Doxygen GUI frontend (Doxywizard) -- load the repository's Doxyfile.
Click File > Open...
The 'Open configuration file' file explorer will appear.
Navigate to your local copy of the dhart repository,
then click the Doxyfile icon.
Your path to the dhart repository will differ, depending where it resides locally on your machine.
Upon loading the Doxyfile, it will be preconfigured for C++.
Doxygen's working directory will be the location of the Doxyfile, which is the root directory of the dhart repository.
The Source code directory will be configured for ./src/Cpp
and the Destination directory will be configured for ./docs/C++.
This is how the 'Wizard' page for Doxywizard may look for a C++ documentation export.
Change the highlighted portion to Csharp for C# sources, or Python for Python sources.
Change the highlighed portion to C# Documentation for C# exports, or Python for Python exports.
Suggestion:
Before exporting documentation and pushing it to the repository,
change the Destination directory to a test directory of your choice
(relative to your local copy of dhart on your machine)
To do this,
create a directory on your Desktop, named test_docs.
Then, for Destination directory,
you will want to provide a relative path to test_docs,
from Doxywizard's working directory.
(this will differ, depending on where your copy of dhart resides on your machine)
For this example, the destination directory is set to move up two parent directories, so that it can reach Desktop/test_docs.
Step 3:
The dhart Doxyfile will be preconfigured to search for images from
dhart\docs, via the IMAGE_PATH variable.
The current IMAGE_PATH value, ./docs should not be removed,
but you may add to it by doing the following:
Click the Expert tab.
Underneath Topics (on the left hand side of the window),
select Input,
then on the right side,
scroll down until you see the text field for IMAGE_PATH.
Click the folder icon for IMAGE_PATH.
In the file explorer window that appears,
navigate to a directory of your choice..
Then, click Select Folder.
You can add to the IMAGE_PATH by selecting any directory of your choice.
The result will be a filepath relative to Doxygen's working directory.
We have now configured another image path for Doxygen.
When Doxygen inserts images into documentation, it will begin its search in the dhart\docs directory.
If you have added another path to IMAGE_PATH (not shown here), it will also search this path.
Step 4:
If there is nothing else you would like to configure,
select the Run tab, then click Run doxygen.
Your documentation will now be generated.
Here are some examples for inserting an image into node.h,
and mainpage.md.
\image tag was used within node.h.
Markdown syntax for images was used for mainpage.md.