Open efiop opened 2 years ago
@daavoo Were there any particular reasons for choosing mkdocs over the other options?
@daavoo Were there any particular reasons for choosing mkdocs over the other options?
Note my points are not really sphinx vs mkdocs but more sphinx vs (mkdocs + ecosystem) .
Mainly chose mkdocs because:
dvc-X
docs doesn't require 90% of sphinx features (and features is the most commonly used point in favor of sphinx).Also:
@casperdcl has introduced some tooling in the shtab
and PyDrive2
recently and there was a discussion I believe around it. Unless there is a really strong reason, I would try to keep it unified if possible.
shtab
: GHA workflow + /docs/ subdir (using pydoc-markdown + custom preprocessor + mkdocs renderer + material theme + markdown_extensions) -> gh-pages branch + CNAME -> https://docs.iterative.ai/shtab/
tqdm
uses :)PyDrive2
: sphinx was a pain, I only changed the theme to furo recently.This is a discussion to have in https://github.com/iterative/py-template. Right now, using markdown in docs is inconsistent with the rest of the cookie-cutter template. Also, we don't need to force docs in all the generated repositories, it should be conditional.
I usually just use sphinx
, coupled with the furo
theme, which is nice and used in lots of Python libraries. There's also myst-parser
that allows you to use markdown with Python and sphinx (which I find to be useful when including readme contents in the docs but use sphinx
's autogeneration features.
using markdown in docs is inconsistent with the rest of the cookie-cutter template
https://github.com/iterative/py-template/blob/main/%7B%7Bcookiecutter.project_name%7D%7D/docs/index.md looks like markdown to me?
using markdown in docs is inconsistent with the rest of the cookie-cutter template
https://github.com/iterative/py-template/blob/main/%7B%7Bcookiecutter.project_name%7D%7D/docs/index.md looks like markdown to me?
template has README.rst
, CONTRIBUTING.rst
and CODE_OF_CONDUCT.rst
.
So, let's try to make it a bit more constructive please? What are the pros and cons of each? I only see some good arguments from @daavoo (thanks, David 🙏 ), everything else so far is not very constructive.
From the top of my head. We mush use MD (so we'll have to introduce additional processing? custom things? - not sure how complicated it is)?
@casperdcl what was your experience with sphinx was a pain
? could you elaborate a bit?
@skshetry what are the cons of using mkdocs?
can we compare the implementation complexity of some examples that we like ?
my understanding:
Compare:
=== tab
, !!! tip
).. toctree:: :maxdepth: 2 <list of pages>
)This is a discussion to have in https://github.com/iterative/py-template.
I have no permissions to transfer the issue there
(My personal preference[^1] is for Sphinx with Furo — like @skshetry in https://github.com/iterative/py-template/issues/19 — plus Napoleon and Google-style documentation strings for the sake of quasiliterate programming)
Projects using Sphinx
Projects using MkDocs
Projects using other systems
[^1]: Shameless plug [^2]: Written in Markdown instead of reStructuredText; doesn't have any API reference, just user guides
Disclaimer: my real-world experience with MkDocs is close to zero. 🤷🏼♂️
While reStructuredText and Sphynx are “the canonical choice” and have lots of specific syntax to represent Python concepts, they're also a bit niche and overcomplicated. I wonder if MkDocs will end up being the “hypermodern” replacement for them.
I've rescued some links from an old direct message conversation with @casperdcl:
@daavoo I can't transfer it either (some limitations may be bc that repo is the fork?)
For the record: just needed to enable issues in py-template first. Transfered.
36% of Python programmers use documentation tools. The most popular one is Sphinx.[^1] #pythondevsurvey https://lp.jetbrains.com/python-developers-survey-2021
[^1]: Sphinx (61%) 🥇 followed by MKDocs (22%) 🥈
In case it's useful, we have a page that lists docs-related repos (and what they use) as of now:
https://www.notion.so/iterative/Docs-related-repositories-list-c23f24dca6154dc49026923ff67d20f4
I would prefer all docs-related repos have a topic documentation
added to them to show up in https://github.com/iterative/?q=topic%3Adocumentation#org-repositories (similar to how we do for topic:example)
Agree. But that doesn't give us details on what engines they use, unless we start including that metadoc in the README or CONTRIBUTE files of every repo.
give us details on what engines they use
oh is that the intention? Why?
Seems like sphinx is the standard (Kudos @pmrowla for the suggestion), but dvc-task and dvc-render use mkdocs. Need to choose.