Generate markdown documentation from C project
  • C 98.2%
  • CMake 0.9%
  • Makefile 0.6%
  • Shell 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
David Heslière c052ffed77
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
Merge pull request 'core/logic' (#15) from core/logic into main
Reviewed-on: #15
2026-11-17 17:32:43 +00:00
.forgejo Fix awk cmd 2026-11-17 17:32:38 +01:00
compat/win32 Fixing windows compiler fail 2026-11-17 11:36:08 +01:00
debian Update versions 2026-11-17 18:34:14 +01:00
src Update versions 2026-11-17 18:34:14 +01:00
.gitattributes Fixing LF line with adding a new step on workflow windows 2026-11-12 15:42:55 +01:00
.gitignore Adding build-cmake/ to .gitignore 2026-11-12 08:14:06 +01:00
CMakeLists.txt Changing the CMakeList.txt in CMakeLists.txt (my bad too strong for this) 2026-11-12 12:40:40 +01:00
LICENSE Add a license 2026-11-15 19:05:50 +01:00
makefile Add debug variables in makefile 2026-11-15 14:06:17 +01:00
PKGBUILD Update versions 2026-11-17 18:34:14 +01:00
README.md Add from binary release instruction in readme 2026-11-17 17:01:56 +01:00

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

cleanbuild target comes with NODEBUG flag

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

See more detailled instructions

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