search

D-K-E / graphical-models

Probabilistic Graphical Models from Scratch with support for LWF Chain Graphs
GNU General Public License v3.0
4 stars 2 forks source link

Documentation Suggestions #4

Open ankurankan opened 3 years ago

ankurankan commented 3 years ago

I think the documentation still needs quite a bit of work.

  1. I would really suggest adding more information to the docstrings: expected parameters, examples for using that method etc. I also think sphinx might be a much better option compared to doxygen for python, just in case you haven't checked it out.
  2. I think the method descriptions can be improved as well. Currently, I see a lot of descriptions just pointing to the reference but I think it would be useful if there is a short description in the docstring as well as the reference for more details.

Ref: https://github.com/openjournals/joss-reviews/issues/3115

D-K-E commented 3 years ago

sphinx might be ...

I tried my hand at sphinx but couldn't manage to configure it. I am also used to doxygen from other projects, so I would like to stick to what I know for now, if you don't think it bothers the user too much. I find that the generated documentation is a little too complex to navigate for a project of this size for example, but I already have a lot of documented code in doxygen markup as well, so I am hesitating to change it now.

more information to docstrings: ... method descriptions ...

I am on it. I hope to finish factor.py by the end of the week. There are several unused functionality as well. I am hoping to clean them up while I am at it.