I'm trying to use Sphinx to auto-generate API documentation for a Python library, and I can't make it properly format the example code snippets in the docstrings - they do get indented but lines of the same indentation get concatenated (https://weka-io.github.io/easypy)
I understand that the problem is that the format I'm using to mark the code blocks is Markdown (indent them by 4 spaces) but Sphinx is expecting reStructuredText (code-block::)
I've tried googling for a solution and it recommended using recommonmark - but it seems to be for using .md files as the source. I'm using sphinx-apidoc to generate the "source" .rst files from the Python code - so it's not going to work (unless there is a way to make sphinx-apidoc generate .md files instead)
So - how do I make Sphinx treat just the Python docstrings as Markdown, leaving the elaborate reStructuredText framework as is for everything else?
Related
I'm using a Sphinx extension (this one) which generates some ReST markup dynamically. Sphinx uses that ReST to generate html documentation.
I want to examine and run doctests on the generated ReST markup. Normally I use
sphinx-build -E -b html docs dist/docs
to generate the html output, but there is no rst "builder" equivalent to the html one.
How can I examine the generated ReST markup?
Use the Sphinx extension sphinx.ext.doctest, following its syntax and markup.
Then run make doctest to run the doctests.
Update
In response to your comments and taking the suggestion from #mzjn, it sounds like you want to generate an intermediate set of documentation that is in reStructuredText. The Sphinx extension restbuilder might be want you seek.
From that point, make doctest might be want you want.
AFAIK, variables can be defined in a YAML external file or inside the Markdown file in a header.
Then they can be used in the document. I have found examples with two different sytaxes:
$variable$ will convert variable to math mode, which is great (i.e. I want to keep that behaviour).
#{variable} does nothing.
Questions:
Is it possible to use variables in the pandoc conversion from markdown to .docx?
If so, how?
Pandoc variables can only be used in pandoc templates, not the document itself (there's an open issue about that).
For that you should check out a preprocessor like gpp or use a pandoc filter like pandoc-mustache or this lua-filter.
I'm working on a book which had a couple of people writing and editing the text. Everything is Markdown. Unfortunately, there is a mix of different styles and lines widths. Technically this isn't a problem but it's not nice in terms of aesthetics.
What is the best way to reformat those files in e.g. GitHub markdown style? Is there a shell script for this job?
You might want to look at Pandoc; it understands several flavors of Markdown.
pandoc -f markdown -t gfm foobar.md
Having written a markup converter years ago in Perl, I would not want to approach such a task without a decent lexical analyzer, which is a bit beyond shell scripting.
I wrote a tool called tidy-markdown that will reformat any Markdown (including GFM) according to this styleguide.
$ tidy-markdown < ./ugly-markdown.md > ./clean-markdown.md
It handles conversion of inline HTML to Markdown, normalization of syntactic elements like code blocks (converting them to fenced), lists, block-quotes, front-matter, headers, and will even attempt to standardize code-block language identifiers.
Is there is list of the markdown tags supported by the redcarpet gem?
For example, some markdown implementations support centering text, some don't. Rather than trial and error experimentation, it seems like such a popular gem would be documented somewhere?
I don't think redcarpet is responsible for the markdown - it's simply a renderer; it uses some libraries to interpret the required code
After some research, it seems all of the markdown interpreters are originally based on the UpSkirt library, which was derived from this Daring Fireball project:
Markdown is a text-to-HTML conversion tool for web writers. Markdown
allows you to write using an easy-to-read, easy-to-write plain text
format, then convert it to structurally valid XHTML (or HTML).
Thus, “Markdown” is two things: (1) a plain text formatting syntax;
and (2) a software tool, written in Perl, that converts the plain text
formatting to HTML. See the Syntax page for details pertaining to
Markdown’s formatting syntax. You can try it out, right now, using the
online Dingus.
You can find the sytnax here
I'm building a Rails app and I'm looking for a way to convert database entries with html and inline MathJax math (TeX) to LaTeX for pdf creation.
I found similar questions like mine:
Convert html mathjax to markdown with pandoc
How to convert HTML with mathjax into latex using pandoc?
and I see two options here:
Create a Haskell executable which leaves stuff like \(y=f(x)\) alone when converting html to LaTeX
Write a ruby method which does the following things:
Take the string and split it into an array with a regex (string.split(regex))
loop through the created array and if content matches regex convert the parts to LaTeX which do not include inline math with PandocRuby.html(string).to_latex
concatenate everything back together (array.join)
I would prefer the ruby method solution because I'm hosting my application on Heroku and I don't like to checkin binaries into git.
Note: the pandoc binary is implemented this way http://www.petekeen.net/introduction-to-heroku-buildpacks)
So my question is: what should the regex look like to split the string by \(math\).
E.g. string can look like this: text \(y=f(x) \iff \log_{10}(b)\) and \(a+b=c\) text
And for the sake of completeness, how should the Haskell script be written to leave \(math\) alone when converting to LaTeX and the ruby method is not a possible solution?
Get the very latest version of pandoc (1.12.2). Then you can do
pandoc -f html+tex_math_dollars+tex_math_single_backslash -t latex