[DOC] Kick-start project documentation

bandang0 commented 4 years ago

Hi, So before we enhance the project I suggest that we kick-start the documentation real quick, that is:

Start the CHANGELOG at the end of README.md
Write a very small description and first usage in README.md
Go through the project and update the present (module and function) docstrings just to make it all a little cleaner.

gabriel-duque commented 4 years ago

Concerning the changelog, wouldn't it be better to have a CHANGELOG file where we append our changelog every time with a specific format?

I am going to check into stuff but if the project ever grows bigger, we could also try sphinx out.

bandang0 commented 4 years ago

Totally agree with the changlog file. For the format did you mean to mention the versions (with semantic versioning?) and list the new features underneath? And maybe the date or something?

We could write all the significant changes from the PR next to the date they were merged, and maybe the PR number. In addition, when a version is released (as it is not the case at every PR merging), we could add the version number.

For example when you merged #2, the change log was:

python classes now
-v flag to turn on verbose
initial test suite

So we could have today the following CHANGELOG.md:


2020.24.02 (#3)
* travis CI
* aamg-gen cli tool

2020.24.02 (#2)
* python classes now
* -v flag to turn on verbose
* initial test suite
* initial generating algorithm

bandang0 / aamg

[DOC] Kick-start project documentation #5