Getting Started¶
> python antiweb.py [options] SOURCEFILETangles a source code file to a rst file.
Options
1 2 3 4 5 6 7 8 9 --version show programs version number and exit -h, --help show this help message and exit -o OUTPUT, --output=OUTPUT The output file/folder name -t TOKEN, --token=TOKEN defines a token, usable by @if directives -w, --warnings suppresses warnings -r, --recursive Process every file in the given directory -d, --daemon starting a daemon which listens for source file changes and automatically updates the resulting documentation files, can only be used together with -r optionIMPORTANT: When combining certain flags, their behaviour may change. When combining the
-o
with the-r
flag,-o
defines the output folder, not the output file.Every @ directive in antiweb has to be a comment in order to be accepted by antiweb. However, antiweb will still recognize but not accept directives which aren’t comments.
@start¶
The
@start
directive defines the beginning of a text block. It is called with an argument defining the name of the text block. There are two special text blocks:
()
The empty one defining the main text block(__macro__)
defining a text block for implementing macros.There are several possibilities to end a text block.
- The end of the file
- A line with a smaller indentation as the
@start
directive.- Another start directive with same indentation.
- An unnamed end (
@
) directive with the same indentation as the@start
directive.- A named end directive closing this block or an outer block.
Text blocks defined by
@start
can be nested.
@rstart(text block name)¶
The@rstart
directive works like the@start
directive. While@start
removes its block completely from the containing block,@rstart
replaces the lines with a<<name>>
- Sentinel.
@cstart(text block name)¶
The
@cstart
directive can be used as a shortcut for:@start(block) @code
@[(text block name)]¶
The end(@
) directive ends a text block. Optional a specific text block can also be closed by defining itstext block name
.
@include(text block name [, file])¶
Once you have created a block you can include it with the
@include
directive. The order in which your blocks will appear in the documentation is defined by the order of the@include
directives@include(Blockname)The directive can have a second file argument. If given, the directive inserts the text block of the specified file.
@RInclude(text block name)¶
The
@rinclude(text block name)
directive is a is a replacement for:.. _text block name: **<<text block name>>** @include(text block name)
@code¶
Of course you want parts of your source code in a Block in order to e.g. describe the function of it. You can do that by following this example. The code in between the directives will be normally recognized as code but also included in the documentation:
1 2 3 4 5 6 7 @code #End of comment section Put your code here #Beginning of next comment section @edoc
@edoc¶
The@edoc
directive ends a previously started@code
directive
Titles¶
There are also different types of titles with different indentation in the index. antiweb wants the indication marks, e.g. #### to be exactly as long as the title. Creating a headline below a higher level headline makes it a sub-headline of the higher one, also shown in the index table
1 2 3 4 5 6 7 8 9 10 ##### Title #This is the top level headline ##### ***** Title #This is the mid level headline ***** Title #This is the low level headline =====
@indent spaces¶
You can indicate antiweb to make a manual indentation with the@indent spaces
directive, replacingspaces
by three would indent the text by three spaces
@define(identifier[, substitution])¶
The@define
directive defines a macro, that can be used with a@subst
directive. If asubstitution
argument is given, the macro defines an inline substitution. Otherwise the@define
has to be ended by an@enifed
directive.
@enifed(identifier)¶
The@enifed
directive ends a macro defined by the@define
directive.
@subst(identifier)¶
The
@subst
directive is replaced by the substitution, defined by a@define
directive. There are two predefined macros:
__line__
- Define the current line within the source code. The
@subst
can also handle operation with__line__
like__line__ + 2
.__file__
- Defines the current source file name.
@if(token name)¶
The@if
directive is used for conditional weaving. The content of an@if
,@fi
block is waved if the named token argument of@if
, is defined in the command line by the--token
option.
@fi(token name)¶
The@fi
ends an@if
directive
@ignore¶
The@ignore
directive ignores the line in the documentation output. It can be used for commentaries.
Indentation matters¶
In sphinx and antiweb, the indentation matters. To effectively nest blocks, create sub headlines and more you have to keep the indentation in mind. To nest a block or headline you have to indent it farther than its parent. In addition, your documentation looks much cleaner when structured like this.