I write documentation for a project using Sphinx. I have code examples (defined as code-blocks, both literally included and just typed inline). In these code examples there are comments, but when I produce documentation translation, they are not extracted into .po files, and obviously are not translated.
How can I translate comments in code examples?
I found other questions about Sphinx modifications. The answers proposed modifying conf.py (making some hooks), creating roles or extensions. I never did that before and I don't know where to start and what solution would be better. Is there any existing solution for this problem?
UPD. These are examples of code I want to show in my documentation:
git clone https://github.com/ynikitenko/lena
# most of requirements are for development only
pip install -r lena/requirements.txt
(here I'd like to translate the comment). A more difficult (maybe not so needed) example is this:
class End(object):
"""Stop sequence here."""
def run(self, flow):
"""Exhaust all preceding flow and stop iteration
(yield nothing to the following flow).
"""
for val in flow:
pass
return
# otherwise it won't be a generator
yield "unreachable"
These examples are formatted with the directive
.. code-block::
I wrote to the official sphinx-users google group, and this is the answer from Matt from Documatt:
It's impossible. Sphinx will have to understand comments in every language.
If you want to translate comments in code-block (and literal blocks after ::), you must translate them all. Add gettext_additional_targets = ["literal-block"] to your conf.py and re-run POT/PO update.
The code lines remain in the "translations" of code, but now the problem is solved for me.
Related
Is there a way to have comments in a _CoqProject file?
I'd like to compile only part of a library, without completely removing all the other files from the _CoqProject file.
# is treated as a comment-the-rest-of-the-line symbol.
I think it is not documented as of now (see issue #7647). But the source code and some experiments show that it works.
In markdown I can write:
[example1][myid]
[example2][myid]
[myid]: http://example.com
so I don't have to retype the full external link multiple times.
Is there an analogous feature in AsciiDoc? Specially interested in the Asciidoctor implementation.
So far I could only find:
internal cross references with <<>>
I think I saw a replacement feature of type :myid:, but I can't find it anymore. And I didn't see how to use different texts for each link however.
Probably you mean something like this:
Userguide Chapter 28.1. Setting configuration entries
...
Attribute entries promote clarity and eliminate repetition
URLs and file names in AsciiDoc3 macros are often quite long — they break paragraph flow and readability suffers. The problem is compounded by redundancy if the same name is used repeatedly. Attribute entries can be used to make your documents easier to read and write, here are some examples:
:1: http://freshmeat.net/projects/asciidoc3/
:homepage: http://asciidoc3.org[AsciiDoc3 home page]
:new: image:./images/smallnew.png[]
:footnote1: footnote:[A meaningless latin term]
Using previously defined attributes: See the {1}[Freshmeat summary]
or the {homepage} for something new {new}. Lorem ispum {footnote1}.
...
BTW, there is a 100% Python3 port available now: https://asciidoc3.org
I think you are looking for this (and both will work just fine),
https://www.google.com[Google]
or
link: https://google.com[Google]
Reference:
Ascii Doc User Manual Link
Update #1: Use of link along with variables in asciidoc
Declare variable
:url: https://www.google.com
Use variable feature using format mentioned above
Using ' Link with label '
{url}[Google]
Using a relative link
link:{url}[Google]
With my team we create software we need to document. I have found doxygen which seems a nice program to do this. Although our programming language is not supported (RAPID).
Yesterday I have asked a question about this. Albert was kind enough to provide a clue in the right direction. A filter should be the right way to go in stead of an preprocessor.
But I did not provide the syntax of the RAPID code which can be found here :
http://futurecnc.code.arc.cmu.edu/wp/wp-content/uploads/2011/12/RAPID-Reference-Manual-Instructions.pdf
I found the help guide about creating filters from the doxygen website. Also i have found an example filter created by Bert Jordan for perl :
http://www.doxygen.nl/helpers.html
Some questions :
Is a filter the right way to go, or is a preprocessor needed ?
What is the filter exactly doing ?
Doxygen has an lexical scanner, what kind of format must be used for the filter to convert the rapid code to a supported language?
I hope, I have given a clear description now :)
edit : I'm searching for information about how to create the actual filter.
Does anybody know a good source for this ?
There are some examples on filters for other languages at the doxygen site under the helpers section.
I have used an doxygen filter (which is not listed there) for Bash for one of my projects. The filter is pretty simple and might be a good example. This filter is available at Anvils github.
In essence it is just a ~130 line sed script converting bash to quasi-C which doxygen can parse. You could write your own sed script for RAPID.
You should add it to your Doxyfile with:
# Tell doxygen to handle files with sh extension as C files
EXTENSION_MAPPING = sh=C
# Tell doxygen to run sh files through the below sed script
FILTER_PATTERNS = *.sh=MY_PATH/doxygen-bash.sed
There is also a python example via the helpers page here.
The main part to understand is that the filter can be anything you like to write. Python, sed, shell, etc. Doxygen just calls your filter, runs the code through it and your filter should output a language Doxygen can parse.
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.
I would like to write a Jekyll plugin that makes all posts available in PDF format by utilizing Kramdown's LaTeX export capabilities. For each post in Markdown format, I'd like to end up with the normal .html post along with a .tex file containing the LaTeX markup and finally a .pdf.
Following the documentation for creating plugins, I see two ways of approaching the problem, either with a Converter or with a Generator.
Converter plugins seem to run after the built-in Converters, so the .markdown files have all been converted to .html by the time they reach the Converter.
When I try to implement a Generator, I am able to use fileutils to write a file successfully, but by the end of Jekyll's cycle, that file has been removed. It seems there's a StaticFile class which you can use to register new output files with Jekyll, but I cannot find any real guidance on how to use it.
If you take a look at the ThumbGenerator class in this: https://github.com/matthewowen/jekyll-slideshow/blob/master/_plugins/jekyll_slideshow.rb you'll seen a similar example. This particular plugin makes thumbnail sized versions of all images in the site. Hopefully it gives a useful guide to how you can interact with Jekyll's StaticFile class (though I'm not a Ruby pro, so forgive any poor style).
Unfortunately, there isn't really documentation for this - I gleaned it from reading through the source.
I wrote this a few months ago and don't particularly remember the details (which is why I gave an example rather than a workthrough), but if this doesn't get you on the right track let me know and I'll try to help.
I try to do the same but with direct html->pdf conversion.
It did not work inside a gitlab-ci pipeline at this time, nonetheless it work on my workstation (see here) with a third possibility : a hook !
(here with pdfkit)
require 'pdfkit'
module Jekyll
Jekyll::Hooks.register :site, :post_write do |post|
post.posts.docs.each do |post|
filename = post.site.dest + post.id + ".pdf"
dirname = File.dirname(filename)
Dir.mkdir(dirname) unless File.exists?(dirname)
kit = PDFKit.new(post.content, :page_size => 'Letter')
kit.stylesheets << './css/bootstrap.min.css'
kit.to_file(filename)
end
end
end