Weird mkdocs RTD behavior

[sagikazarmark]

I don't know why, but RTD works weird with our mkdocs architecture. Github links don't work at all.

I was doing some research, but haven't found anything.

Here is an article about RTD and mkdocs and it works fine there:

http://www.sitepoint.com/building-product-documentation-mkdocs/

I also found an article explaining how to use sphinx for MD. It would allow us to generate PDFs as well.

http://searchvoidstar.tumblr.com/post/125486358368/making-pdfs-from-markdown-on-readthedocsorg-using

https://github.com/ericholscher/sphinx-markdown-test/

[sagikazarmark]

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

readthedocs/readthedocs.org#1884

[marcelstoer]

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.

[sagikazarmark]

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

Leaving this open until the linked issue is resolved.

[marcelstoer]

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.

[sagikazarmark]

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. 😉

[dbu]

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.

[sagikazarmark]

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?

[dbu]

i don't know, with foshttpcache we only have 2 levels: http://foshttpcache.readthedocs.org

[sagikazarmark]

Maybe we should also limit to two level?

[sagikazarmark]

I guess this isn't relevant anymore.