- C 98.2%
- CMake 0.9%
- Makefile 0.6%
- Shell 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
Create doc, publish it to wiki and send webhook / documentation (push) Successful in 12s
Release / preparation (push) Successful in 3s
Release / arch-compile (push) Successful in 6s
Release / debian-compile (push) Successful in 6s
Release / windows-compile (push) Successful in 55s
Release / release (push) Successful in 6s
Check Project syntax health / syntax (arch) (push) Successful in 8s
Check Project syntax health / syntax (windows-latest) (push) Successful in 39s
Reviewed-on: #15 |
||
| .forgejo | ||
| compat/win32 | ||
| debian | ||
| src | ||
| .gitattributes | ||
| .gitignore | ||
| CMakeLists.txt | ||
| LICENSE | ||
| makefile | ||
| PKGBUILD | ||
| README.md | ||
docc-to-md
Generate doc for a C project into markdown
Pronounced "dok C to MD"
Usage
Get a markdown documentation for a C projet, for example for a Forgejo wiki page
Arguments list
When the binary is compiler (see installation to compile it/download it), you can run it with these arguments :
| Argument | Type | Effect | State | Default |
|---|---|---|---|---|
--src |
String | Specify the entry point of the project to read from | Required | N/A |
--dest |
String | Specify the path of the output markdown. If is is not found, it will be created | Required | N/A |
--work |
String | Specify the work directory of the project. It will be used to put temp files for comment removal | Optional | /tmp/docc-to-md |
--help |
Toggle | Displays help page and exits. If specified, has priority on any other argument | Optional | N/A |
--version |
Toggle | Displays program version and exits. If specified, has lower priority than --help, but priority over anything else |
Optional | N/A |
-d |
Toggle | Enables dump. This is to get a raw output of the parsed content | Optional | N/A |
--dump |
String | Specify dump files path. If not exists, it will be created and truncated | **Required if and only if -d specified |
N/A |
--verbose-registration |
Toggle | If specified, it will enable the print to the standard output of the name and type of each element registered, the summary of the parsing and the summary of the linkage | Optional | N/A |
--enable-docstirng |
Optional | At the cost of more computing, enable the linkage of docstring to functions, typedefs, macros and structures. It finds the content within /* and */ above the mentionned items |
Optional | N/A |
--rebase-path |
String | If not specified, the absolute path of the local files will be shown, as display and link in documentation. If specified : in links, the display will be the individual filenames, relative to the root of the project (specified by --src), and the link will be pointing to whatever this argument specifies immediately followed by the relative path of the file to the project root |
Optional | N/A |
--git-line |
Toggle | If enabled, add #line-number-reference of the elements in the link of their definition file. it is useful for git repositories so it links directly to the definition. Useful in large files |
Optional | N/A |
--reference-files |
Toggle | If enabled, add a section at the end of each documentation file, specifying which file are referenced inside the specific documentation file | Optional | N/A |
--pre-linkage |
Toggle | If enabled, includes an additional step between parsing and linkage. It is used to enhance the resulting documentation, by sorting objects by name (using quick sort). On very large projects with a lot of objects, it might not be recommended | N/A |
Usage examples
As previously stated, this was originnaly designed to generate documentation for Forgejo wiki pages. It could be applicable to other services as well
Please contact me if you want to improve/suggest anything
This repository contains a wiki creation and synchronisation workflow. Here are the relevant parts :
# Compiling step
/usr/bin/docc-to-md --src src --dest "$WIKI_DIR" --verbose-registration --enable-docstring --reference-files --git-line --pre-linkage --rebase-path $URL/src/branch/main/
# Later on :
## Publishing step
WIKI_URL="$SERVER_URL/$REPO_NAME.wiki.git"
AUTH_HEADER="Authorization: Basic $(printf '%s' "$WIKI_USERNAME:$WIKI_TOKEN" | base64 | tr -d '\n')"
rm -rf wiki
if git clone "$WIKI_URL" wiki; then
echo "Wiki cloned"
else
mkdir wiki
git -C wiki init
git -C wiki checkout -b main
fi
find wiki -maxdepth 1 -type f -name 'api-*.md' -delete
find wiki -maxdepth 1 -type f -name 'api.md' -delete
rm -rf wiki/*
cp -v "$WIKI_DIR"/*.md wiki/
cd wiki
git add .
git -c user.name="forgejo docs" \
-c user.email="docs@noreply.$SERVER_URL" \
commit -m "Update generated API documentation" || true
if ! git remote get-url origin >/dev/null 2>&1; then
git remote add origin "$WIKI_URL"
fi
git -c http.extraheader="$AUTH_HEADER" push -u origin HEAD
⚠️ Some forgejo instances cannot programmatically create a wiki if it doesn't exist. That's why the original workflow has a message on failure
Examples
See the wiki page of this repository, it has been generated with docc-to-md
Installation
From binary
See the release section to install pre-compiled binaries
From source
git clone https://git.greensky.tf/Greensky/docc-to-md && cd docc-to-md
make cleanbuild
sudo mv bin/main.uwu /usr/bin/docc-to-md
or :
git clone https://git.greeensky.tf/docc-to-md && cd docc-to-md
cmake CMakeLists.txt
make -f Makefile
Compile arguments list You can include these arguments right in the compilation command, for example :
make DBG_POSITION
| Argument | Type | Effect |
|---|---|---|
NODEBUG |
Int | Disable debug macros if set to anything |
DISABLE_DEBUG |
int | Same as NODEBUG |
DBG_POSITION |
int | Enables position prefix in debugging macros if set to anything |
DBG_BLOCK |
int | Enables the real time clock in debug macros if set to anything |
DBG_NO_COL |
int | Disables default color in debug macros if set to anything |
cleanbuildtarget comes withNODEBUGflag
From PKGBUILD (arch)
If you are using arch, you can install it through the PKGBUILD file :
curl -o PKGBUILD https://git.greensky.tf/Greensky/docc-to-md/src/branch/master/PKGBUILD
makepkg -siCcf
From repository
The PKGBUILDING repository continuously compiles a version of this file and publishes it
Roadmap
This is essentially a list of things to do, so I don't forget
| What | Importance | Notes | Status |
|---|---|---|---|
| Macros parsing | High | N/A |
✅ |
| Structures parsing | Necessary | N/A |
✅ |
| Functions parsing | Necessary | N/A |
✅ |
| Typedef parsing | Necessary | N/A |
✅ |
| Typedef functions parsing | High | Typedefs don't register functions typedefs for now | ✅ |
| Include docstring for other types | Medium | For now, only the functions take the docstring | ✅ |
| Unamed functions arguments resolving | Low | Finish the resolving of unamed function arguments. This is mainly for arguments that are custom structs/enums/typedefs or standard types that don't fit in one word | ✅ |
| Types resolving | Necessary | Needs the typedef parsing to be done | ✅ |
| Markdown writing | Necessary | Needs types resolved | ✅ |
| Pre Linkage | Optional | Add a prelinkage phase to do things like sorting types | ✅ |
| Type modifiers | Important | Introduce type modifiers (like constant, volatile...) | ✅ |
| Windows Portability | Low | Check installation steps on Windows install | ✅ |
Legend :
🚧 : Planned
🏗️ : Working on it
❌ : Aborted
✅ : Done
Contact
Since the code makes a lot of assumptions and purposely ignores some valid C cases, like :
enum Thing
{
};
is not recognized as an enum.
If you want to help to improve the project, and/or have any request regarding the project, please contact me on this discord server, My matrix space, or by email