reStructuredText allow you extend/rewrite writer for its markup. So you can add new type of embedded objects or introduce new sub-language by defined API.
Is this possible with Asciidoc (original Python implementation or Ruby asciidoctor)?
Yes to both, though the ways to extend each are different. In the Python implementation there's a conf file you use to create additional regex matchers. In asciidoctor (ruby) there is a full extension system built into versions starting at 0.1.4 (though it was at preview level in 0.1.4). Visit http://asciidoctor.org/docs/user-manual/#extension-points for more information about extensions in asciidoctor. http://asciidoc.org/userguide.html#X7 for asciidoc.
Related
I like to add additional macros to asciidoctor for these types:
path:[some path value]
label:[some label text]
replace:[some value to become replaced by the user]
screen:[something the users sees on screen]
I mainly want to have it rendering some CSS classes while rendering to HTML5. I found several sources on how to write a macro for asciidoctor, but I do not get the point. Where to place or insert the ruby code and classes I write? Here is an example page I found: https://docs.asciidoctor.org/asciidoctor/latest/extensions/inline-macro-processor/
But I found no simple step-by-step information about where to place that?
Can someone tell me:
In which file(s) shall I add my macro code?
How to enable this in general for asciidoctor (so I can simply call it without the need to put it into the comandline call. Or do I have to register the macro in the call all the time?
I installed asciidoctor on Ubuntu 20.04 using apt-get install asciidoctor. Seems it works so far. But I found no files for the predefined macros btn, kbd and menu.
I'm a little lost here... Any help is appreciated.
PS. I know the syntax [.label]#some label text# to place CSS classes, but I want to have it generic and also usable for PDF generation later.
After many different tries and research I finally found it to be easy. Just point asciidoctor to the file you want to include by using the -r comandline parameter:
asciidoctor -r ~/tools/asciidoctor_patch/include_asciidoc.rb
Sadly, the whole asciidoctor documentation names this parameter only "require" and does not even mention this to be used for extensions. I also found no source that mentions the use of -r for including the macros.
Is there a way to sort my #include statements in Clion? Additionally, can I do this automatically every time I save? I didn't manage to find any such functionality or plugin.
Yes, it is possible with help of clang-format.
File->Settings...->Languages & Framework->C/C++->Clangd->Enable clangs server
clang-format should be installed in your system. Normally it is available in your favourite repository. You can specify the path to it if required
File->Settings...->Tools->clang-format
You have to put .clang-format file into your project root with coding rules. More information you can find on clang-format web site. For example, I am using Google coding rules. My content looks like this:
Language: Cpp
BasedOnStyle: Google
This includes already the include statements sorting. However, there is a choice of other ready-to-use coding styles like LLVM, Mozilla, WebKit, Chromium which you can use and if necessary modify or you can create your own format by providing set of rules you want. The rule you might be interesting in is
SortIncludes (bool)
If true, clang-format will sort #includes.
Please refer to the clang format documentation here
I document a Python project using Sphinx and the Napoleon and the autodoc extension to parse Google style docstrings. As the Google style involves specifying the type of the arguments, Sphinx automatically creates links to the documentation of the standard types in the standard library. Intersphinx However, by default it links to the 2.7 version of the documentation, whereas I want to link to a 3.x version. How can I control this behaviour?
How the Python library is linked is controlled by the intersphinx extension. Set
intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None)}
in conf.py and the links should link to the Python 3 standard library.
See intersphinx docs for more information on how to use intersphinx.
When working with Nunjucks templates which requite rendering or compilation is there a standard naming convention to be used to have them processed? i.e. file.nunjucks, file.nunjucks.html, or file.njs etc.
I know that when working with other template languages it's common to use their name as the extension such as file.liquid, file.ejs, etc, but I've not seen much in reference to Nunjucks.
I personally prefer the extension '.njk', its also something that they have as an example on the Nunjucks docs.
File Extensions
Although you are free to use any file extension you wish for your Nunjucks template files, the Nunjucks community has adopted .njk.
If you are developing tools or editor syntax helpers for Nunjucks, please include recognition of the .njk extension.
Jon Buckley's nunjucks plugin for
wintersmith supports template naming convention
*.html
*.nunjucks
See https://github.com/jbuck/wintersmith-nunjucks/issues/8 for proof
So this naming convention is common everywhere wintersmith site generator is used. Especially the *.html seems to be fairly common also elsewhere.
Nunjucks's own documentation uses the *.html in examples of using {% include ..%} and {% extends ..%} tags and it says
...overview of the templating features available in nunjucks. Nunjucks is essentially a port of jinja2, so you can read their docs if you find anything lacking here...
and jinja's own documentation in turn says
...A template is simply a text file. It can generate any text-based format (HTML, XML, CSV, LaTeX, etc.). It doesn’t have a specific extension, .html or .xml are just fine...
My in-house site generator applies the nunjucks preprocessor also to files with extensions: *.md, *.markdown, *.htm, *.html, *.php, *.css, *.js, .htaccess but it can not be considered "common convention".
It might be possible to find out nunjuck's usage statistics and examples of used naming conventions using Google or GitHub or Wolfram Alpha computational knowledge engine or IBM Watson Analytics service...
I think that you can use any naming convention as long as you are able to refactor (rename) it anytime later
Is it possible to generate RDoc in LaTeX format? I looked at RDoc and YARD, but didn't find what I need.
I am writing a documentation in LaTeX for my project in Ruby, and I need a way to easily embed the API reference, as an appendix or as a chapter, in the final PDF. The most convenient, for me, would be to generate LaTeX source from Ruby source files and include it where appropriate.
I have no experience with it, but a short google-search shows:
https://github.com/Quintus/rdoc_pdf-latex (link broken, see below)
http://www.ruby-doc.org/core-1.9/classes/RDoc/Markup/ToLaTeX.html (link broken)
Another possibility:
DO you know the listings-package in LaTeX? There is also a ruby support.
You would get no rdoc-commands, but maybe you could make LaTeX-commands in your code?
Papyrus is a plugin for RDoc that enables RDoc to generate PDF files. It's based on LaTeX. So there should be a intermediate TeX-file.
From the readme.rdoc of the github repository for papyrus:
This library is a plugin for Ruby’s documentation generator RDoc. It provides both a generator for outputting PDF (Portable document format) (the RDoc::Generator::Papyrus class) files and a formatter for turning the parsed RDoc markup into LaTeX code (RDoc::Markup::ToLaTeX; RDoc::Markup::ToLaTeX_Crossref adds cross-reference facilities).