Weird mkdocs RTD behavior about documentation HOT 10 CLOSED

Hm, it seems to be a new issue. Let's wait if it gets solved.

readthedocs/readthedocs.org#1884

from documentation.

I also found an article explaining how to use sphinx for MD

It's also briefly explained in the official RTD docs at http://docs.readthedocs.org/en/latest/getting_started.html?highlight=markdown#in-markdown. I tried because it looked promising but since the implementation is based on CommonMark it was a dead end for us. In its current form CommonMark is just a no go because its scope is so limited and the pace at which the project moves forward is really slow. Not even markdown tables are supported.

from documentation.

Thanks for your input @marcelstoer, you probably saved us a lot of time.

Leaving this open until the linked issue is resolved.

from documentation.

I don't intend to lead you away from Sphinx & CommonMark, not at all. Do you own analysis by all means.

I spent some time reading through the CommonMark community postings and their current issues to get a feeling for what their intent is and how they go about things. As much as I like to idea of a Markdown "standard" I realized that my own ideas don't align very well with the CommonMark project so I didn't pursue that any further.

MkDocs and RTD have their own issues (localization is weird, not PDF/HTML export), I keep finding more and more bugs (mkdocs/mkdocs#774, mkdocs/mkdocs#770, mkdocs/mkdocs-bootswatch#5). So, I'm not really happy but I haven't found a better alternative yet.

from documentation.

The only reason I wanted to experiment with Sphinx is the issue linked above.

To tell the truth, I am amazed how many people use Sphinx with all the mess it comes with. I am sure it is fully configurable, so I am speaking for myself, but out of the 5 tries, I simply stopped playing with sphinx each time because it's complicated, etc.

I can live without PDF export, so if one day I will have plenty of time, I will definitely try Sphinx. Until then: no thanks. 😉

from documentation.

i am using sphinx with restructured text (rst) with good success. see foshttpcache, symfony-cmf and also the symfony docs. i don't know how much symfony people struggled to get http://symfony.com/doc/ run smoothly, but for simpler cases like foshttpcache on readthedocs it works nicely.

not saying we should convert everything from markdown to rst now (we had that discussion before) but maybe sphinx just works better with rst than md.

from documentation.

sphinx just works better with rst than md

That's something I agree with.

Another thing: the readthedocs theme with mkdocs does not really handle 3 level deep paths. Is the "original" theme with sphinx and rst better in it?

from documentation.

from documentation.

Maybe we should also limit to two level?

from documentation.

I guess this isn't relevant anymore.

from documentation.