Open kdheepak opened 5 years ago
I don't have an opinion here.
I might look into mkdocs as @kdheepak previously suggested, or even back to Sphinx if that gets a good overall integrated site down the line. We're adding more general docs, not specific to Julia. Sphinx-Julia is not archived yet, so it might work, otherwise even a custom script might generate better docs for the use case here.
With Documenter.jl, we can't even (easily) add links to the sidebar. There are many open issues in its repo with feature requests that might bear fruit someday, but since the documentation is one of the first impressions for new users, it might be better to use something without so many limitations in our context.
The Python packages were updated to use Markdown with MyST instead of reStructuredText, and I'm pretty happy with the results so far: https://dss-extensions.org/OpenDSSDirect.py/
Franklin.jl is another option on the Julia side. I'm not sure it can crank out doc strings like Documenter, though.
mkdocs
supports more extensions and themes (See https://squidfunk.github.io/mkdocs-material/) and imho looks nicer. However, The default documentation allows looking at multiple versions using a drop down. Withmkdocs
we'll need to either add a separate markdown file with links to older versions or write some additional html / css / js to make that work. Any thoughts?