-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.md.in
130 lines (100 loc) · 6.58 KB
/
README.md.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
# @PROJECT_NAME@
[](https://sonarcloud.io/project/overview?id=ggabbiani_orthodocs)
## @PROJECT_DESCRIPTION@
@ODOX_PACKAGE_DESCRIPTION@. For the list of the feature planned and their status see [Project status](#project-status). For an example of the produced documentation see [OFL Table of Contents](https://github.com/ggabbiani/OFL/blob/main/orthodocs/toc.md) or browse the [OFL documentation tree](https://github.com/ggabbiani/OFL/tree/main/orthodocs).
For OrthoDocs installation see [Installing `OrthoDocs`](INSTALL.md).
## How to document
@PROJECT_NAME@ is able to recognize all the public global functions, modules and variables found in the source tree, complete with parameters and their default values. Sources can be passed as files, directories or both. Each source file (here referred to as *package*) will produce a corresponding API document.
- [@PROJECT_NAME@ basics](unit-tests/docu-styles/ortho/lib-nocomments/README.md) - documenting uncommented code
- [Using decorations](unit-tests/docu-styles/ortho/lib-defdecorations/README.md) - default behavior
- [Using custom decorations](unit-tests/docu-styles/ortho/lib-custom-decorations/README.md) - customized decoration
- [Using comments](unit-tests/docu-styles/ortho/lib-nodecorations/README.md) - documenting existing code
## The command line
@PROJECT_NAME@ is a CLI only utility, the basic invocation is:
orthodocs --src-root «path to source-root directory» --doc-root «path to document-root» «list of files and/or directory relative to source-root»
@PROJECT_NAME@ will search in all the input directories for any scad file, the resulting file list being merged with the files eventually passed as positional and analyzed.
The analysis results will be used for producing a number of Markdown documents (one for each
source file analyzed).
Assuming the following directory tree:
/home/
└── giampa/
└── example/
└── sources/
├── 2d.scad
├── annotated.scad
├── bbox.scad
├── type_trait.scad
└── uncommented.scad
the following command executed in the directory «/home/giampa»
/home/giampa $ orthodocs --src-root example/sources --doc-root example/docs
will scan all the SCAD sources in the source-root and produce the consequent documents in the doc-root
/home/
└── giampa/
└── example/
├── docs/
│ ├── 2d.md
│ ├── annotated.md
│ ├── bbox.md
│ ├── type_trait.md
│ └── uncommented.md
└── sources/
├── 2d.scad
├── annotated.scad
├── bbox.scad
├── type_trait.scad
└── uncommented.scad
If we want to keep the same source-root **while documenting only a subset** of the present sources the following command
/home/giampa $ orthodocs --src-root example/sources --doc-root example/docs annotated.scad uncommented.scad
will produce
/home/
└── giampa/
└── example/
├── docs/
│ ├── annotated.md
│ └── uncommented.md
└── sources/
├── 2d.scad
├── annotated.scad
├── bbox.scad
├── type_trait.scad
└── uncommented.scad
### Full command options
For more complex tasks consult the full command option list:
| Option | Description
| ------------------ | -----------
| -a,--admonitions | **FLAG** - When this flag is enabled any admonition found in annotations will be enriched with a corresponding emoji
| --data-dir | **OPTION** - Absolute path to data directory: touch only if you know what you do
| --decorations | **OPTION** - Defines the prefix used inside comments to distinguish a simple comment from an annotation. Set to '' means no decorations, and all the comments are interpreted as annotations.
| -d,--doc-root | **OPTION** - Specifies the target document tree root either as absolute or current directory relative path. It is a **mandatory directory** parameter and - if not existing - it will be automatically created.
| -g,--graphs | **OPTION** - List of root relative directories where placing dependency graphs. Needs --src-root.
| -h,--help | **FLAG** - Print the help message and exit
| -i,--ignore-prefix | **OPTION** - Ignore this prefix in the Table of Contents when sorting
| -o,--orthodox | **FLAG** - Comments for parameters are **preceding** their formal definition.
| --unorthodox | **FLAG** - Comments for parameters are **following** their formal definition.
| -p,--private | **OPTION** - Every documentation item (variable, function or module) prefixed with this string will not be published.
| --pd,--pkg-deps | **OPTION** - Set package dependencies representation by text list or by a dependency graph (possible value **text**/**graph**, default to **text**)
| -s,--src-root | **OPTION** - Source tree root - either an absolute or current directory relative path. It is a **mandatory existing directory** parameter.
| sources | **POSITIONAL** - source sub-trees and/or files -
| -t,--toc | **FLAG** - Generate a Table of Contents in the document tree root either as absolute or «source tree root» relative path
| -V,--verbosity | **OPTION** - Set the message log verbosity
| -v,--version | **FLAG** - Display program version information and exit
## Project status
The list of features expected in the v1 release with their current status:
| Feature | Status
| ------------------------- | ------
| [admonitions](https://www.markdownguide.org/hacks/#admonitions)| ✔
| comment styles | ✔
| cross-reference | ✔
| dependency graphs | ✔
| global values | ✔
| source license detection | ✔
| table of contents | ✔
## Supported OSs
| OS | Build | Run | Package
| ------------- | ----- | --- | -------
| Fedora Linux | ✔ | ✔ | ✔
| macOS | ✔ | ✔ | ✔
| Ubuntu Linux | ✔ | ✔ | ✔
| Windows | ✔ | ✔ | ✔