E-CAM example module¶
The E-CAM library is purely a set of documentation that describes software development efforts related to the project. A module for E-CAM is the documentation of the single development of effort associated to the project.In that sense, a module does not directly contain source code but instead contains links to source code, typically stored elsewhere. Each module references the source code changes to which it directly applies (usually via a URL), and provides detailed information on the relevant application for the changes as well as how to build and test the associated software.
The original source of this page (readme.rst) contains lots of additional comments to help you create your
documentation module so please use this as a starting point. We use Sphinx (which in turn uses ReST) to create this
documentation. You are free to add any level of complexity you wish (within the bounds of what Sphinx and ReST can
do). More general instructions for making your contribution can be found in “How to contribute?”.
Remember that for a module to be accepted into the E-CAM repository, your source code changes in the target application must pass a number of acceptance criteria:
- Style (use meaningful variable names, no global variables,…)
- Source code documentation (each function should be documented with each argument explained)
- Tests (everything you add should have either unit or regression tests)
- Performance (If what you introduce has a significant computational load you should make some performance optimisation effort using an appropriate tool. You should be able to verify that your changes have not introduced unexpected performance penalties, are threadsafe if needed,…)
Purpose of Module¶
Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how it fits into the larger picture of what you want to achieve. The overview should be comprehensible to a scientist non-expert in the domain area of the software module.
This section should also include the following (where appropriate):
- Who will use the module? in what area(s) and in what context?
- What kind of problems can be solved by the code?
- Are there any real-world applications for it?
- Has the module been interfaced with other packages?
- Was it used in a thesis, a scientific collaboration, or was it cited in a publication?
- If there are published results obtained using this code, describe them briefly in terms readable for non-expert users. If you have few pictures/graphs illustrating the power or utility of the module, please include them with corresponding explanatory captions.
Note
If the module is an ingredient for a more general workflow (e.g. the module was the necessary foundation for later code; the module is part of a group of modules that will be used to calculate certain property or have certain application, etc.) mention this, and point to the place where you specify the applications of the more general workflow (that could be in another module, in another section of this repository, an application’s website, etc.).
Note
If you are a post-doc who works in E-CAM, an obvious application for the module (or for the group of modules that this one is part of) is your pilot project. In this case, you could point to the pilot project page on the main website (and you must ensure that this module is linked there).
If needed you can include latex mathematics like
which won’t show up on GitLab/GitHub but will in final online documentation.
If you want to add a citation, such as [CIT2009], please check the source code to see how this is done. Note that citations may get rearranged, e.g., to the bottom of the “page”.
| [CIT2009] | This is a citation (as often used in journals). |
Background Information¶
If the modifications are to an existing code base (which is typical) then this would be the place to name that application. List any relevant urls and explain how to get access to that code. There needs to be enough information here so that the person reading knows where to get the source code for the application, what version this information is relevant for, whether this requires any additional patches/plugins, etc.
Overall, this module is supposed to be self-contained, but linking to specific URLs with more detailed information is encouraged. In other words, the reader should not need to do a websearch to understand the context of this module, all the links they need should be already in this module.
Building and Testing¶
Provide the build information for the module here and explain how tests are run. This needs to be adequately detailed, explaining if necessary any deviations from the normal build procedure of the application (and links to information about the normal build process needs to be provided).
Source Code¶
Here link the source code that was created for the module. If you are using Github or GitLab and the Gitflow Workflow you can point to your feature branch. Linking to your pull/merge requests is even better. Otherwise you can link to the explicit commits.
There may be a situation where you cannot do such linking. In this case, I’ll go through an example that uses a patch file to highlight my source code changes, for that reason I would need to explain what code (including exact version information), the source code is for.
You can create a similar patch file by (for example if you are using git for your version control) making your changes for the module in a feature branch and then doing something like the following:
[adam@mbp2600 example (master)]$ git checkout -b tmpsquash
Switched to a new branch "tmpsquash"
[adam@mbp2600 example (tmpsquash)]$ git merge --squash newlines
Updating 4d2de39..b6768b2
Fast forward
Squash commit -- not updating HEAD
test.txt | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git commit -a -m "My squashed commits"
[tmpsquash]: created 75b0a89: "My squashed commits"
1 files changed, 2 insertions(+), 0 deletions(-)
[adam@mbp2600 example (tmpsquash)]$ git format-patch master
0001-My-squashed-commits.patch
To include a patch file do something like the following (take a look at the source code of this document to see the syntax required to get this):
1 2 3 4 5 6 7 8 9 10 11 | Always remember that a good patch file should have a comment inside about what the patch is for....just like this
--- hello.c 2014-10-07 18:17:49.000000000 +0530
+++ hello_new.c 2014-10-07 18:17:54.000000000 +0530
@@ -1,5 +1,6 @@
#include <stdio.h>
-int main() {
+int main(int argc, char *argv[]) {
printf("Hello World\n");
+ return 0;
}
|
If the patch is very long you will probably want to add it as a subpage which can be done as follows
you can reference it with Patch file for module