dssg/aequitas

Update GitHub pages

sgpjesus opened this issue · 1 comments

The current solution for documentation generation for GitHub pages (link here) has some flaws. These are:

  1. New packages, classes, etc. are not included and the process to include them is unclear.
  2. The build of documents is stored in the package, cluttering the docs directory.
  3. The code documentation lacks some aspects (code examples, type hints).
  4. The license is of 2018.
  5. The style is outdated.
  6. 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.

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)