Basically I want to write one piece of text which qualifies both as a working code and MarkDown (preferably GitHub flavor) for documentation. The language I'm using has C form commenting \\ for rest-of-line and /* ... */ for multi line comments. So far what I can do is:
/* --> start with multi line comments
here some markdown text
# heading
* list
end markdown section with
<!--- */ // -->
or
[//]: # (end of comment block --> */ // <-- inline comment)
_-_-indented code
_-_-_-_-more indented code
The issues are:
the first /* still showing in the documentation
I can't use the proper multiline code block ``` ... ```. I have to indent the code parts once more than what is required. Also the syntax highlighting doen't work in this format AFIK.
I would appreciate if you could help me know first how to solve above issues. and Secondly if there is any better way to do this?
I think I have a proper solution now with colapsible / foldable code section:
/*
This is the markdown **text**
used for documentation
<details>
<summary>Click to see the source code</summary>
``` scilab
*/
This is the
actual code
which will
be executed
/*
```
</details>
<!--- */ // -->
which will be rendered as:
/*
This is the markdown text
used for documentation
*/
This is the
actual code
which will
be executed
/*
The collapsible section makes sure that the documentation is clean and readable. you may see the final result here on GitHub. I used the code from here. Now there are a bunch of /*s and */s which would be nice to get ride of. Next step would be to modularize the MarkDown document into different files as I have asked here.
P.S. Implementation of the same idea using AsciiDoc here.
Related
The following section in sphinx
.. math::
\vb{R} = \vb{T} \vb{U}^{-1} = \vb{V}^{-1} \vb{T}
is rendered as
What I actually want is this:
But right now this is only possible if I write
.. math::
\mathbf{R} = \mathbf{T} \mathbf{U}^{-1} = \mathbf{V}^{-1} \mathbf{T}
or by including the \require{physics} tag in the ..math block, which is not ideal since this is also part of a docstring that is being documented with sphinx autodoc.
I have already tried to adopt the solution from this thread by adding
mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax#3/es5/tex-mml-chtml.js"
to my conf.py file, but it did not work. How can I properly display desired latex code on my website?
Adding
mathjax3_config = {
'loader': {'load': ['[tex]/physics']},
'tex': {'packages': {'[+]': ['physics']}},
}
to the conf.py resolves the issue by instructing MathJax to load the physics package.
Ho can I include inside an asciidoc code fence? Here is a sample:
[source,js]
----
function doit() {
*var thing;* // local variable
}
----
The idea is that I would like to highlight certain parts of the code block for teaching purposes.
The above sample doesn’t work.
I have read about using something like [subs="macro"], but (a) I can’t get it working in combination with a code fence, and (b) the documentation is a little unclear about the actual details.
Thanks
BTW I am aware of a similar question AsciiDoc add bold text inside a listing block, but there is no reference to code fences. I have tried the solutions, but the don’t work in this context.
According to AsciiDocs Documentation, below code
[source,java,subs="verbatim,quotes"]
----
System.out.println("Hello *bold* text").
----
will be displayed as
System.out.println("Hello bold text").
So, you need this -
[source,js,subs="verbatim,quotes"]
----
function doit() {
*_var thing;_* // local variable
}
----
It will be displayed as
verbatim and quotes subs are helpful.
NOTE:
One thing we need to keep in mind that the code block is already highlighting syntax. If you want different formatting, better not to use code block.
In my opinion the philosophy of Asciidoctor for those use case is to use callouts.
[source,js]
----
function doit() {
var thing; // <1>
}
----
<1> local variable
The second thing you should consider is to extract your code from a real, controled, unit-tested file. You define some markers in this code file and add an include directive in your adoc file.
Check slides 15-21 in this presentation:
Writing documentation with Asciidoctor
Is there a way to comment M code / comment out lines or blocks of code?
M supports two different types of comments:
Single line comments can be started with //
You can comment out multiple lines or comment out text in the middle of a line using /* */ (e.g. = 1 + /* some comment */ 2)
Comments might seem to disappear in the formula bar if they are at the end of the line, but they are still there. You can verify this by looking at your code in the Advanced Editor.
In C#, is there a reason why multi-line /* */ comments can't overlap? This also applies to HTML (and I'm sure lots of other languages) too.
e.g.
/*
int a = SomeFunction();
/* int i = 0; */
int b = SomeFunction();
*/
won't compile.
When writing code I often want to quickly check the logic, and isolate certain parts by removing a section using multi-line comments, but then have to go through the code block replacing all multi-line comments with single line ones //.
I don't like using single line comments to comment-out code blocks (even though Visual Studio provides shortcuts to do this) as these then affect text comments when it comes to removing all comments in the block using the shortcut.
Is there a reason why the multi-line comment cannot mean: 'ignore everything between here'?
I'm afraid this is the way how it's designed.
I think you should use single line comments as much as possible. It's also much clearer when you are viewing the history of a file in source control. If you commented an entire method with /* */ then only two lines will appear changed, otherwise the entire method will have been changed (// added).
I would like to know whether it is possible to define own doxygen comment styles. The usual style is something like this (Javadoc-like):
/**
*
* Descriptions and stuff
*
*/
or (when using Qt):
/*!
*
* Descriptions and stuff
*
*/
I would prefer something like
/*!===============================================================
*
* Descriptions and stuff
*
================================================================*/
But the doxygen parser doesn't allow this syntax. So my questions is, if there is a way to define own comment styles.
I don't think you can define your own comment styles, but with some slight changes to the format, it might match.
See this page on documentation blocks in the Doxygen documentation:
Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:
/********************************************//**
* ... text
***********************************************/
(note the 2 slashes to end the normal comment block and start a special comment block).
or
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////