Extract docs from source

mkdocs.yml

# This examples shows how you can extract markdown from a source file.
site_name: ok-source-extract
plugins:
  - simple

Input

ok-source-extract/
├── main.c
├── mkdocs.yml
├── module.py
└── README.md

main.c

#include <stdio.h>

/** md
## Detailed documentation

### block comments

block comments are added with `/** md` and conclude with `**\/` tags.
**/

// md
// ### line comments
// 
// line comments are added with `// md` and conclude with `// end md` tags
// end md
int main() {
  printf("Hello, world!");
  return 0;
}

module.py

"""md

## Python Version

You can put _markdown_ in triple-quoted strings in Python.
"""

# md
# ### inline comments
#
# It works in inline comments. The start and end markers must be on their own
# lines.
# /md


def main():
    # noqa: D207
    """<md trim=4 >Main test.

    ### docstrings

    It works in docstrings. The start and end quotes must be on their own lines.
    You can even tell it to remove leading whitespace with the 'trim' option.
    """
    print("Hello, world!")
    return 0

Output

site/
├── assets/
│   ├── images/
│   │   └── favicon.png
│   ├── javascripts/
│   │   ├── lunr/
│   │   │   └── min/
│   │   └── workers/
│   └── stylesheets/
├── index.html
├── main/
│   └── index.html
└── module/
    └── index.html

main

Detailed documentation

block comments

block comments are added with /** md and conclude with **\/ tags.

line comments

line comments are added with // md and conclude with // end md tags

module

Python Version

You can put markdown in triple-quoted strings in Python.

inline comments

It works in inline comments. The start and end markers must be on their own lines.

docstrings

It works in docstrings. The start and end quotes must be on their own lines. You can even tell it to remove leading whitespace with the 'trim' option.