Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Weird mkdocs RTD behavior #53

Closed
sagikazarmark opened this issue Dec 28, 2015 · 10 comments
Closed

Weird mkdocs RTD behavior #53

sagikazarmark opened this issue Dec 28, 2015 · 10 comments

Comments

@sagikazarmark
Copy link
Member

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
Copy link
Member Author

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

readthedocs/readthedocs.org#1884

@marcelstoer
Copy link

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
Copy link
Member Author

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

Leaving this open until the linked issue is resolved.

@sagikazarmark sagikazarmark changed the title Use sphinx for markdown rendering Weird mkdocs RTD behavior Dec 29, 2015
@marcelstoer
Copy link

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
Copy link
Member Author

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
Copy link
Contributor

dbu commented Dec 31, 2015

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
Copy link
Member Author

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
Copy link
Contributor

dbu commented Dec 31, 2015 via email

@sagikazarmark
Copy link
Member Author

Maybe we should also limit to two level?

@sagikazarmark
Copy link
Member Author

I guess this isn't relevant anymore.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants