search

koaning / scikit-fairness

this repo might get accepted
https://scikit-fairness.netlify.app/
29 stars 9 forks source link

Documentation: Sphinx or Mkdocs #20

Closed koaning closed 4 years ago

koaning commented 4 years ago

Now is the time to decide on the direction of documentation. Part of me is in favor of using mkdocs instead of sphinx.

There's a few reasons.

  1. Markdown is the lingua-franka now and .rst is a bottleneck when it comes to getting folks to contribute.
  2. Mkdocs has nice customisation features and we can still make an amazing API doc. The downside is that the docstrings will need to be written in a new style. See example here (expand the source code button).
koaning commented 4 years ago

@MBrouns got a strong preference here?

MBrouns commented 4 years ago

I like markdown quite a bit over rst so I'm all for it. You used the mkautodocs plugin a bit before right? If you say it's good then I'd say go for it

koaning commented 4 years ago

I might get started on a variant with mkdocs then.

koaning commented 4 years ago

Sphinx is more stable now.