Context
While trying to preserve the formatting of a specific piece of output in a README.md file, I noticed I was not able to find an explanation on how to ignore a rule in the documentation. (Neither for the command line arguments, nor for the .pre-commit-config.yml.) Hence I would like to ask:
Question
How does one ignore rule:MD013 for mdformat in a .pre-commit-config.yml file?
Ideally, I would be able to include a comment inside the README.md file that tells mdformat to ignore rule MD013 for the next line, or next block of lines. Similar to:
# pylint: disable=R09013
Pre-commit config
The relevant piece of the .pre-commit-config.yml is:
# Enforces formatting style in Markdown (.md) files.
- repo: https://github.com/executablebooks/mdformat
rev: 0.7.14
hooks:
- id: mdformat
#args: ["-r ~MD013"]
additional_dependencies:
- mdformat-toc
- mdformat-gfm
- mdformat-black
Related
I have a project where one repeatable task to do involves manipulating files' contents.
Until now I used a Python script for it, but recently I discovered I can use standalone CMake scripts ("standalone" here means they can be invoked outside of configure/build/test/etc. workflow). As my project already uses CMake for project management I concluded I can save others' problem of installing a Python interpreter (welcome Windows users!) and use CMake project-wide.
Part of my script needs to read a file and cut off everything that appears before "[START-HERE]" and after "[END-HERE]" lines. I am stuck with that part and don't know how to implement it. How can it be done?
You could combine file(READ) with if(MATCHES) to accompilish this. The former is used to read the file, the latter allows you to check for the occurance of a regular expression and to extract a capturing group:
foo.cmake
#[===[
Params:
INPUT_FILE : the path to the file to read
#]===]
file(READ "${INPUT_FILE}" FILE_CONTENTS)
if (FILE_CONTENTS MATCHES "(^|[\r\n])\\[START-HERE\\][\r\n]+(.*)[\r\n]+\\[END-HERE\\]")
# todo: use extracted match stored in CMAKE_MATCH_2 for your own logic
message("Content: '${CMAKE_MATCH_2}'")
else()
message(FATAL_ERROR "[START-HERE]...[END-HERE] doesn't occur in the input file '${INPUT_FILE}'")
endif()
foo.txt
Definetly not
[START-HERE]
working
[END-HERE]
Try again!
Output:
> cmake -D INPUT_FILE=foo.txt -P foo.cmake
Content: 'working'
For the part where you are stuck, here's one approach using the string, file, and math commands:
file(READ data.txt file_str)
string(FIND "${file_str}" "[START-HERE]" start_offset)
# message("${start_offset}")
math(EXPR start_offset "${start_offset}+12")
# message("${start_offset}")
string(FIND "${file_str}" "[END-HERE]" end_offset)
math(EXPR substr_len "${end_offset}-${start_offset}")
# message("${substr_len}")
string(SUBSTRING "${file_str}" "${start_offset}" "${substr_len}" trimmed_str)
# message("${trimmed_str}")
You could also probably do it by using the file(STRINGS) command, which reads lines of a file into an array, and then use the list(FIND) command. The approach shown above has the advantage of working if your delimiters are not on their own lines.
As #fabian shows in their answer post, you can also do this using a regular expression with if(MATCHES) like this:
file(READ "${INPUT_FILE}" FILE_CONTENTS)
if (FILE_CONTENTS MATCHES "(^|[\r\n])\\[START-HERE\\][\r\n]+(.*)[\r\n]+\\[END-HERE\\]")
# todo: use extracted match stored in CMAKE_MATCH_2 for your own logic
message("Content: '${CMAKE_MATCH_2}'")
else()
message(FATAL_ERROR "[START-HERE]...[END-HERE] doesn't occur in the input file '${INPUT_FILE}'")
endif()
I am writing a book with bookdown. Unfortunately, I have no clue how to format (e.g. setting font size) ATX-hearder (#, ##, ## etc.). So far, it does not work via pandoc or preamble.tex.
I have tried the following, with regard to this.
Unfortunately, there is an error message :
\usepackage{titlesec} \titleformat{\chapter}[display] {\normalfont\sffamily\huge\bfseries\color{blue}} {\chaptertitlename\ \thechapter}{20pt}{\Huge}
Thanks in advance!
Your best bet here is to add a LaTeX preamble to the document. In here, you can define the required LaTeX packages. Two changes are made to the base template:
We need to add subparagraph: true to make titlesec work with R Markdown, as explained here
# refers to a level one header in pandoc, and therefore you need to make the style changes for section not chapter https://www.sharelatex.com/learn/Sections_and_chapters
Here is a minimal example
---
output:
pdf_document:
includes:
in_header: header.tex
subparagraph: true
---
# Section
## Subsection
The preamble.tex file is saved in the same directory:
\usepackage{titlesec}
\usepackage{color}
\titleformat*{\section}{\LARGE}
\titleformat{\subsection}[display]
{\normalfont\sffamily\huge\bfseries\color{blue}} {\chaptertitlename\ \thechapter}{20pt}{\Huge}
I'm working on the documentation of a component using Doxygen and I want to include UMLdiagrams in between the text.
I know how to do most of it, as I simply need to copy the .tuml source into my .dox file and run doxygen. However, one of my diagrams is a class diagram that includes other .iuml files, like explained in the PlantUML site.
So, basically, I do:
#mainpage main_page MyDoxygen
\
...
\
#startuml
\
!include iuml_files/Class01.iuml
!include iuml_files/Class02.iuml
\
MainClass <|-- Class01
MainClass <|-- Class02
\
#enduml
Long story short, I don't know how to make Doxygen understand it must look for the .iuml files in the directory (relative path) I'm giving as argument to the include directive.
If I wasn't clear enough as to what I need, please let me know and I will try make it clearer.
Can I please get some help?
I had a similar problem (I own the Word Add-in for plantuml)
You can specify the java property "plantuml.include.path" in the command line :
java -Dplantuml.include.path="c:/mydir" -jar plantuml.jar atest1.txt
(see http://plantuml.sourceforge.net/preprocessing.html)
I expect it'll work when you modify the batch file for calling Plantuml
http://plantuml.sourceforge.net/doxygen.html
I had a similar request for my Word Addin for Plantuml and here it worked.
The Real Answer
Use the PLANTUML_INCLUDE_PATH = ./someRelativeDir configuration, visible in the Doxygen wizard's DOT panel.
The include path is relative to your Doxygen config, ie the starting directory from which the doxygen config is taken.
A Red Herring
I'm leaving the rest of this answer here in case anyone found it previously.
I wrongly reported a bug because I needed new reading glasses and didn't notice a stray character in my path.
This was resolved as not a Doxygen bug
For any interested parties, this is what I saw.
Running PlantUML on generated file /Users/andydent/dev/touchgramdesign/doxygeneratedTG4IM/html/inline_umlgraph_1.pu
Preprocessor Error: Cannot include /Users/andydent/dev/touchgramdesign/doxygeneratedTG4IM/html/handDrawnStyle.iuml
Error line 2 in file: /Users/andydent/dev/touchgramdesign/doxygeneratedTG4IM/html/inline_umlgraph_1.pu
Some diagram description contains errors
error: Problems running PlantUML. Verify that the command 'java -jar "/Library/Java/Extensions/plantuml.jar" -h' works from the command line. Exit code: 1
This is using the configuration setting
PLANTUML_INCLUDE_PATH = ./iumltToCopy
Sharper eyes than mine (at the time) noticed the extra character in the path iuml t ToCopy
I find myself in a situation where I would like to accurately document a host of custom CMake macros and functions and was wondering how to do it.
The first thing that comes to mind is simply using the built-in syntax and only document scripts, like so:
# -----------------------------
# [FUNCTION_NAME | MACRO_NAME]
# -----------------------------
# ... description ...
# -----------------------------
This is fine. However, I'd like to employ common doc generators, for instance doxygen, to also generate external documentation that can be read by anyone without looking at the implementation (which is a common scenario).
One way would be to write a simple parser that generates a corresponding C/C++ header with the appropriate signatures and documentation directly from the CMake script, which could the be processed by doxygen or comparable tools. One could also maintain such a header by hand - which is obviously tedious and error prone.
Is there any other way to employ a documentation generator with CMake scripts?
Here is the closest I could get. The following was tested with CMake 2.8.10. Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.
CMake 2.8 can extract documentation from your modules, but only documentation at the beginning of the file is considered. All documentation is added as CMake comments, beginning with a single #. Double ## will be ignored (so you can add comments to your documentation). The end of documentation is marked by the first non-comment line (e.g. an empty line)
The first line gives a brief description of the module. It must start with - and end with a period . or a blank line.
# - My first documented CMake module.
# description
or
# - My first documented CMake module
#
# description
In HTML, lines starting with at two or more spaces (after the #) are formatted with monospace font.
Example:
# - My custom macros to do foo
#
# This module provides the macro foo().
# These macros serve to demonstrate the documentation capabilietes of CMake.
#
# FOO( [FILENAME <file>]
# [APPEND]
# [VAR <variable_name>]
# )
#
# The FOO() macro can be used to do foo or bar. If FILENAME is given,
# it even writes baz.
MACRO( FOO )
...
ENDMACRO()
To generate documentation for your custom modules only, call
cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html
Setting CMAKE_MODULE_PATH allows you to define additional directories to search for modules. Otherwise, your modules need to be in the default CMake location. --help-custom-modules limits the documentation generation to custom, non-CMake-standar modules. If you give a filename, the documentation is written to the file, to stdout otherwise. If the filename has a recognized extension, the documentation is formatted accordingly.
The following formats are possible:
.html for HTML documentation
.1 to .9 for man page
.docbook for Docbook
anything else: plain text
I am trying to use some Doxygen filter for Visual Basic in Windows.
I started with Vsevolod Kukol filter, based on gawk.
There are not so many directions.
So I started using his own commented VB code VB6Module.bas and, by means of his vbfilter.awk, I issued:
gawk -f vbfilter.awk VB6Module.bas
This outputs a C-like code on stdin. Therefore I redirected it to a file with:
gawk -f vbfilter.awk VB6Module.bas>awkout.txt
I created this Doxygen test.cfg file:
PROJECT_NAME = "Test"
OUTPUT_DIRECTORY = test
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = awkout.txt
QUIET = NO
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE = NO
To produce the documentation I issued:
doxygen test.cfg
Doxygen complains as the "name 'VB6Module.bas' supplied as the second argument in the \file statement is not an input file." I removed the comment #file VB6Module.bas from awkout.txt. The warning stopped, but in both cases the documentation produced was just a single page with the project name.
I tried also the alternative filter by Basti Grembowietz in Python vbfilter.py. Again without documentation, again producing errors and without any useful output.
After trials and errors I solved the problem.
I was unable to convert a .bas file in a format such that I can pass it to Doxygen as input.
Anyway, following #doxygen user suggestions, I was able to create a Doxygen config file such that it can interpret the .bas file comments properly.
Given the file VB6Module.bas (by the Doxygen-VB-Filter author, Vsevolod Kukol), commented with Doxygen style adapted for Visual Basic, I wrote the Doxygen config file, test.cfg, as follows:
PROJECT_NAME = "Test"
OUTPUT_DIRECTORY = test
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = readme.md VB6Module.bas
QUIET = YES
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE = NO
FILTER_PATTERNS = "*.bas=vbfilter.bat"
where:
readme.md is any Markdown file that can used as the main documentation page.
vbfilter.bat contains:
#echo off
gawk.exe -f vbfilter.awk "%1%"
vbfilter.awk by the filter author is assumed to be in the same folder as the input files to be documented and obviously gawk should be in the path.
Running:
doxygen test.cfg
everything is smooth, apart two apparently innocuous warnings:
gawk: vbfilter.awk:528: warning: escape sequence `\[' treated as plain `['
gawk: vbfilter.awk:528: warning: escape sequence `\]' treated as plain `]'
Now test\html\index.html contains the proper documentation as extracted by the ".bas" and the Markdown files.
Alright I did some work:
You can download this .zip file. It contains:
MakeDoxy.bas The macro that makes it all happen
makedoxy.cmd A shell script that will be executed by MakeDoxy
configuration Folder that contains doxygen and gawk binaries which are needed to create the doxygen documentation as well as some additional filtering files which were already used by the OP.
source Folder that contains example source code for doxygen
How To Use:
Note: I tested it with Excel 2010
Extract VBADoxy.zip somehwere (referenced as <root> from now on)
Import MakeDoxy.bas into your VBA project. You can also import the files from source or use your own doxygen-documented VBA code files but you'll need at least one documented file in the same VBA project.
Add "Microsoft Visual Basic for Applications Extensibility 5.3" or higher to your VBA Project References (did not test it with lower versions). It's needed for the export-part (VBProject, VBComponent).
Run macro MakeDoxy
What is going to happen:
You will be asked for the <root> folder.
You will be asked if you want to delete <root>\source afterwards It is okay to delete those files. They will not be removed from your VBA Project.
MakeDoxy will export all .bas, cls and .frm files to location:<root>\source\<modulename>\<modulename>(.bas|.cls|.frm)
cmd.exewill be commanded to run makedoxy.cmd and delete <root>\source if you've chosen that way which alltogether will result in your desired documentation.
A logfile MakeDoxy.bas.logwill be re-created each time MakeDoxy is executed.
You can play with configuration\vbdoxy.cfg a little if you want to change doxygens behavior.
There is still some room for improvements but I guess this is something one can work with.