Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
moving docs to mkdocs #856
Move all docs to mkdocs
Still to do:
@@ Coverage Diff @@ ## master #856 +/- ## ====================================== Coverage 100% 100% ====================================== Files 17 16 -1 Lines 3132 2716 -416 Branches 610 518 -92 ====================================== - Hits 3132 2716 -416
I think the new (hierarchical) organization is a big improvement; it's not just a massive wall of text. I'm not sure that by itself necessitated the move to mkdocs though.
I can't speak for what motivated @samuelcolvin to move to mkdocs, but I personally think it now looks much nicer than the old docs page, and hopefully feels a little more modern for prospective new users.
And at least one person has commented positively (from the fastapi gitter):
@haizaar Do you have any issues with new docs format?
@dmontagu not at all. They are aesthetically pleasing. Though there are nice sphinx templates our there as well. And of course you can create hierarchical docs with sphinx as well. I wonder if material design was the main thing. Or may be Samuel just wanted get some experience with mkdocs :)
Again, I have absolutely no problems/issues with the docs. Just being curious.
1. Markdown vs. reStructuredText
Many developers find markdown much more intuitive to use than rst. I know rst has many powerful features but it's also extraordinarily convoluted to do simple things e.g. links are
I find this amazingly complex. Even after having written thousands of lines of it, I still have to search for an example of things that are trivial in md.
I hope people will be more willing to help with the docs now they're written in markdown.
2. mkdocs vs. sphinx
mkdocs definitely isn't perfect, there are some design decisions I strongly disagree with. However overall it's a lot more use friendly than sphinx:
Not really, though I do think it's nice.
If only, we used a mkdocs site for the help site of the company I run for many years. mkdocs is an old frenemy.