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.
Related
I'm rather new to Sphinx and ReST and I've "inherited" a big project.
The documentation consists of hundreds of pages with how to's, etc. There are several files (one for each class) where the respective functions are described using the ".. py:function::" directive.
So each of these pages is basically like this:
Some description text explaining the class
py:function:: class.myFunction(param1, param2)
parameter description
code example, ...
py:function:: class.myFunction2
parameter description
code example, ...
Now, I'd like to list all functions of all different pages in one single XML file, if possible grouped by their class, but without the descriptions and examples. Is this possible with some built-in Sphinx parser or do I have to write my own? Or is there any other directive or config option that may be helpful?
The XML file should be like this:
<class1>
<function1>
<param1>
<param2>
...
<function2>
...
<class2>
<function1>
...
I found ViewLists and the Parsing directive in the Sphinx documentation but i'm not sure how to correctly use them and if that's the solution to my problem.
I use sphinx to generate HTML and PDF documentation, and was using latex until now to generate PDF, but now looking at swapping for rinohtype.
I'm looking at setting up some custom headers and footers, but would like to include variable text into them, for the version number for example, which comes from a sphinx python plugin. I have rst substitutions, for example |version|, that I use in various places in the document, but if I add it to the header via a stylesheet it doesn't get substituted. I also have python variables, for example version, in my conf.py so I also tried to use {version} in my stylesheet, but the builder complains that the variable doesn't exists.
FYI, here is how I tried to define my header :
[contents_page]
header_text = '|document_id| |version| |shortdate|' (header)
[contents_page]
header_text = '{document_id} {version} {shortdate}' (header)
Any idea how to get around that issue ?
Thanks
rinohtype does support including reStructuredText substitutions (|subst|) in document templates, but this is one of the features that isn't documented yet.
To use substitutions in a page header or footer, you need to include them as follows:
[contents_page]
header_text = '{UserStrings.document_id} {UserStrings.version} {UserStrings.shortdate}' (header)
(Actually, I don't remember why I require the UserStrings. prefix. Perhaps there is a good reason for that. If not, that prefix might not be needed in the future.)
Short story: I'm using Markdown to write a novel. Long story is here. In this site I typo-check the text using a Perl module (which I also developed), but I'd like to check MD syntax too. However, most markdown tool seem to be too lenient on errors, letting go stuff like this
This is an *error
This would be [another error](
Besides, there is no "check-only" option that returns false when there's an error, so that it can be used in continuous integration tests. The only one that balks out in this stuff is maruku. Kramdown, pandoc, marked, markdown (for nodejs), all of them let it go without a glitch.
Question is, is there a markdown syntax validator or checker in any language I can use easily in CI? Or should I go with maruku, despite being considered obsolete by his authors?
As pointed out in this answer, "it is impossible to write "invalid" markdown only markdown that wont do what you want it to." Every string is valid markdown.
You could, however define a subset of markdown that excludes markdown like the examples you mentioned in the question, and modify an existing parser to adhere to that subset.
We implemented a magento module https://github.com/firegento/firegento-pdf/ and I plan to write tests for the module.
The problem is: The extension generates pdfs.
Is there any framework, or whatever to test pdfs? It would be totally fine if I can check for text in the pdf. I don't want to check the correct placement.
Andy ideas?
This looks promising but feels oversized. http://webcheatsheet.com/php/reading_clean_text_from_pdf.php
I use PdfBox for a similar module, a Java based command line utility that extracts text from a PDF and optionally converts it to HTML: http://pdfbox.apache.org/commandline/#extractText
To use it within PHPUnit tests, I wrote a PHP interface for the relevant PdfBox methods: https://github.com/schmengler/PdfBox
Example
use SGH\PdfBox;
//$pdf = GENERATED_PDF;
$converter = new PdfBox;
$converter->setPathToPdfBox('/usr/bin/pdfbox-app-1.7.0.jar');
$text = $converter->textFromPdfStream($pdf);
Further reading: Unit Test Generated PDFs with PHPUnit and PDFBox
Maybe you could use Inkscape to convert it into SVG and make asserts on some SVG Nodes.
That would do if you only want to check the text or some simple formatting.
$ inkscape -f invoice.pdf --export-plain-svg=thepdf.svg
For the correct position you need to be a bit fuzzy, though.
Nevertheless the PDF source can be plain enough to be checked with simple strpos().
You have to resign yourself to testing "we sent the right commands to Magento". Testing the output PDF would cause fragility.
Mock the PDF-writing library, and test that your code called the library correctly. This has the added benefit of speed, but requires a little more discipline. If a PDF output fails a manual inspection, you MUST fix that test-first, to keep your mocks honest.
I am generating a PDF via Sphinx using the autogenerated Makefile. I usually generate it using:
make latexpdf
However, I am now including the only directive, so that some sections appear conditionally (this should happen if I include the relevant tag at the command line).
I added the following reST markup to my source file:
Hello world
.. only:: draft
This is some draft content.
I tried generating the PDF as follows:
SPHINXOPTS="-t draft" make latexpdf
...but the output is the same as if I'd just run make latexpdf as normal, the "only" section does not appear. Is there a problem in my reST or my command line invocation?
(Also, I'd like to specify multiple tags if possible, e.g. draft and admin.)
You need to modify the command a little (the variable assignment must come after make). Either of these work for me (using GNU make):
make SPHINXOPTS="-t draft" latexpdf
or
make latexpdf SPHINXOPTS="-t draft"