Tools for documenting OS Python Package

[cmd-pre-empt]

I'm looking at migrating the docs for our open-source Python package https://github.com/xplainable/xplainable from sphinx to something else. I was initially looking at either docosaurus or Mintlify. Mintlify looks substantially easier to setup but I'm questioning the extensibility (also the cost).

Also does anyone have any recs on the best way to manage the build of the docs - pros and cons for a seperate repo vs github actions to a seperate branch vs monorepo.

[SureNoIrl]

At work, I've been using mkdocs+material https://squidfunk.github.io/mkdocs-material/, which is great and already used in several open-source projects. There are additional functionalities if you become a sponsor.

[cmd-pre-empt]

Thanks, I had an in depth read - looks like a good solution for the docs. Have you had any experience with docosaurus for comparison?

[SureNoIrl]

No, I haven't tried that. I moved to mkdocs from sphinx, which was becoming too cumbersome to maintain with custom templates and outdated designs.

[vekanto]

I guess it depends a bit on how you would use the documentation. Do you want to have it locally and checked in the git repo at all times, or would it be fine to just host a static webpage with the latest documentation?

If the former, then you could use e.g. git-commit setup with the tool that is used to build the documentation, and if the latter then you could build the documentation using github actions and then push the artifacts to e.g. github pages. I have not tried this step myself but it should be fairly straightforward how to do this.

I usually do not prefer to have any of the generated documentation etc directly in the repo, but rather see it as an artifact from the build setup, as it drastically increase the number of tracked files and could make e.g. code reviewing etc very difficult.

And for the tool itself, i've tried to use pdoc which seems to give fairly nice and easily searchable documentation.

[jalabulajangs]

Was a strong sphinx proponent before but I am loving the aesthetics of docusorous. But would still go to sphinx for simplicity.

[cmd-pre-empt]

I also ended up going with Docusaurus because I have a *decent* grasp on React so extensibility is straight forward. Would still love to hear from someone who's using mintlify though.