Update GitHub pages
sgpjesus opened this issue · 1 comments
sgpjesus commented
The current solution for documentation generation for GitHub pages (link here) has some flaws. These are:
- New packages, classes, etc. are not included and the process to include them is unclear.
- The build of documents is stored in the package, cluttering the
docs
directory. - The code documentation lacks some aspects (code examples, type hints).
- The license is of 2018.
- The style is outdated.
- There is no landing page.
The current solution is based on sphinx (used in many projects). How do they organize it?
Following the example of sklearn
, there is a mix of both generated and explicitly written documentation in the rst
files.
- Example of an explicit documentation page: Tree,
rst
. - Example of a generated documentation page: DecisionTreeClassifier,
docstring
(No idea how examples notebooks are put in the generated docs).
Sphinx is the basis of documents for many packages (torch
is a giant one but super messy, sklearn
in between, fairlearn
is smaller and pretty clean).
Style is is normaly stored in _static/css
or have a dedicated directory for the effect (the case of Sklearn
).
Landing pages are a bit weird to see how they are done.
sgpjesus commented
Tasks:
- Fix the error messages when compiling documentation
- Add the missing classes (relevant ones) to the documentation
- Reduce number of pages in the index.rst
- Make the examples page better
- Add favicon with a nice Aequitas logo (check if it exists, create if it doesn't)
- Add versioning
- (add more)