Pandoc support

[SilleBille]

Details

• Read the Docs project URL:
• Build URL (if applicable):
• Read the Docs username (if applicable):

Expected Result

This request may be turned down. But, giving my shot

I'm pretty new to readthedocs and I was impressed by the features. Thanks for this awesome project!
While researching, I came across pandoc which isn't supported by readthedocs (or at least, I don't find it in the tutorial).

I am trying to achieve the following:
A set of markdown files that:
a. is generated in the form of linux man pages
b. is generated into HTML

With the help of pandoc, I'm able to achieve the above 2. However, I am not able to host it on readthedocs. Is there a possiblity to add support for pandoc?

Actual Result

No way to build with pandoc and deploy to readthedocs

[humitos]

Hi @SilleBille! Read the Docs currently achieve 2 -- generate HTML from Markdown.

Also, Sphinx -- the builder that RTD uses -- has the ability to generate man pages but we are not doing that currently. Although, there is an issue already open for that #4458

Would it be enough for you to enable man page generation for Sphinx builder?

[SilleBille]

@humitos thanks for the reply! To summarize my needs with a simplified diagram:

• javadoc is generated using the official javadoc package
• man pages are currently processed using pandoc
• Documentation can also be converted to HTML by pandoc. Using sphinx/mkdocs for just this workflow makes the pipeline complicated.

I want to keep the pipeline as simplified as possible.

To answer your question, though sphinx supports all the above, as per your previous comment, it seems rtfd doesn't provide support for man pages? Yes, I can switch over to sphinx if man pages can be generated in both roff and HTML formats

[humitos]

Thanks for the explanation.

I think this is a very fair feature request considering that we support sphinx and mkdocs. Why not pandoc also?

I don't have too much experience with pandoc (I've only used it to convert files between formats and it's great) and I don't know how much complicated it would be, but I'm sure that it's not an easy feature to add to our platform. On the other hand, considering our current roadmap, I don't think that this will happen soon, unfortunately.

I marked this issue as Needed: design decision so other core developers can write their thoughts here.

To answer your question, though sphinx supports all the above, as per your previous comment, it seems rtfd doesn't provide support for man pages? Yes, I can switch over to sphinx if man pages can be generated in both roff and HTML formats

Currently, we are not generating man pages. So, I'd say that it's not supported. The discussion for this will happen in #4458

[SilleBille]

@humitos Thanks for an optimistic reply. The main concern for me is that I don't want my team to follow different formats to write down the documentation. I want them to follow consistent formatting across all the docs they write.

[humitos]

I'm assuming that we won't implement this at a Read the Docs level as another builder for the documentation. Instead, we will probably put more effort on allowing #1083, so the user can build the documentation using the custom workflow needed and then upload the docs already built.

[humitos]

I'm going to close this issue since it's not going to happen soon, unfortunately. We can revisit later if we consider valuable to add another builder. Thanks!

[Jacob-Stevens-Haas]

Adding a link here because I found this issue before the relevant, older one, but it looks like readthedocs has pandoc support already: #579 (comment).

Sphinx uses a conf.py, which "itself can be an extension; for that, you only need to provide a setup() function in it". (ref1, ref2). This can include calls to the pandoc python wrappers..

If you need a different version of pandoc binaries, you can specify it in your readthedocs.yml.