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.)
Related
I want to use the .. include:: function inline, but I can only get it to actually include the file I want if I separate it with two new lines from the previous text.
Before anyone asks, the file I want to include is a protocol number, so no, it doesn't benefit from a new line, at all. I want to be able to change it easily so I can use it on multiple places of my documentation. I guess that an example would be "We currently use the protocol (proto.txt)." I'm new to Sphinx and rst, so maybe there is a very obvious solution I haven't found.
Inline includes are not possible with Sphinx.
However, you can define global aliases (substitutions) in the rst_epilog variable of your build configuration file.
For example, you can add the following lines to your conf.pyfile:
rst_epilog = """
.. |version| replace:: 4.1
.. |protocol| replace:: httpx
"""
Now, you can access the variables |version| and |protocol| from any .rst file within your project, for example like this:
Version |version| uses the |protocol| protocol.
becomes
Version 4.1 uses the httpx protocol.
If other parts of your software require protocol (or other variables) to be specified in a specific file or format, you can write a script to read it from there as a variable into the Sphinx configuration file.
Description:
I am trying to integrate a workflow and tools which incorporates vimwiki and Gollum. I want to merely add vimwiki as an extention type for the editor while being processed by Gollum's internal Markdown processor (see "Things I've tried" #1).
Eventually I'd also like to have Gollum default to 'vimwiki' when creating new documents as well.
The project I'm working on can be found at Vimwiki-Gollum-Integration
Testing Specifics:
Gollum version: 4.1.1
The file being tested is valid github markdown
The same content is being tested with different filenames and extensions:
testx.thing
blah.vimwiki
The test files do work fine when they are named with .md extensions
relevant rendering gems installed:
github-markdown
github-markup
kramdown
redcarpet
All code is being tested in a gollum --config file
I'm not well versed in ruby
Things I've tried
Creating a new extension and custom renderer
This works except there is no reason to implement a custom processor (pandoc)
This would be ideal so that the Markdown name ends up in the Edit page. However, I don't think I should have to involve pandoc here
How in the heck do I get the edit page to default the markdown to vimwiki when editing a vimwiki extension?
file used: blah.vimwiki
# always include this:
Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES
################### custom extension + renderer
# # Custom extension rendering
# ## References
# * file reference: /var/lib/gems/2.1.0/gems/github-markup-1.6.0/lib/github/markup/command_implementation.rb
# * [Adding Pandoc to Gollum - Martin Wolf's weblog [OUTDATED]](https://www.mwolf.net/2014/04/29/adding-pandoc-to-gollum/)
ci = ::GitHub::Markup::CommandImplementation.new(
/vimwiki/,
["Vimwiki"],
"pandoc -f markdown-tex_math_dollars-raw_tex",
:vimwiki)
# bind your own extension regex (the new set of extensions will also include `.asc` and `.adoc`):
# # * file reference: /var/lib/gems/2.1.0/gems/github-markup-1.6.0/lib/github/markups.rb
Gollum::Markup.register(:vimwiki, "Vimwiki")
Gollum::Markup.formats[:vimwiki][:regexp] = /vimwiki/
GitHub::Markup::markup_impl(:vimwiki, ci)
##################
Attempt to replace the Markdown primary extension and regex.
I don't understand why this isn't working unless I'm misunderstanding the order of operations for matching and overrides.
The page will display, the extension is recognized, but the page does not format at all -scrunches everything together.
# always include this:
Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES
# Attempt to replace the primary extension for Markdown
# remove the original markdown binding:
Gollum::Markup.formats.delete(:markdown)
# and define your own
Gollum::Markup.formats[:thing] = {
:name => "Markdown",
:regexp => /thing/
}
Attempt to just replace the markdown extension regex
Same result as attempt 2.
The page will display but it is not formatted correctly
# always include this:
Gollum::Page.send :remove_const, :FORMAT_NAMES if defined? Gollum::Page::FORMAT_NAMES
Gollum::Markup.formats[:markdown][:regexp] = /vimwiki|thing/
I'm closing the question:
As it turns out there is no way easy way to use the markdown processor and also get the edit page to recognize that there is a different extension. The markdown processor requires the extension to be valid it it's regex of extensions found in markdown.rb.
The bottom line is that I would need to implement something similar to what pandoc is doing anyway. So I'm just going just drop the subject and stick with pandoc -'Things I've tried #1' from the original question.
Rather than take a bunch of space here I've posted the documentation on the project page with code examples
Thank you to whomever spent some time thinking about this.
I want to use the .. include:: function inline, but I can only get it to actually include the file I want if I separate it with two new lines from the previous text.
Before anyone asks, the file I want to include is a protocol number, so no, it doesn't benefit from a new line, at all. I want to be able to change it easily so I can use it on multiple places of my documentation. I guess that an example would be "We currently use the protocol (proto.txt)." I'm new to Sphinx and rst, so maybe there is a very obvious solution I haven't found.
Inline includes are not possible with Sphinx.
However, you can define global aliases (substitutions) in the rst_epilog variable of your build configuration file.
For example, you can add the following lines to your conf.pyfile:
rst_epilog = """
.. |version| replace:: 4.1
.. |protocol| replace:: httpx
"""
Now, you can access the variables |version| and |protocol| from any .rst file within your project, for example like this:
Version |version| uses the |protocol| protocol.
becomes
Version 4.1 uses the httpx protocol.
If other parts of your software require protocol (or other variables) to be specified in a specific file or format, you can write a script to read it from there as a variable into the Sphinx configuration file.
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 am struggling with this issue:
I have to document a fairly large project composed by a C core engine and different API that are built on top of that, say Java, Python C#.
The docs must be deployed separately for each API, i.e. for each language, but 99% of the docs are the same, just the code snippet and example mainly need to change.
I set the type of language in the conf.py file by defining a global variable
I have used primary_domain and highlight_language to set the correct syntax highlighting
For each example I have a source file with the same name but different extension
Now, I'd like to include say an example using the literalinclude directive specifying the name of the file and let its extension change depending on the language in use. I tried naively to use the replace macro but with no success:
rst_prolog = ".. |ext| replace:: .%s\n" % primary_domain
correctly replace |ext| around the docs, but not in the command
.. literalinclude: filename|ext|
Is there any way I can do this, except parse rst files using sed or the like?