Modo🧯 -- DocGen for Mojo🔥

# Modo🧯

<br />

### 🔥

---

## What is Modo🧯?

### <big>↓</big>

----

Modo🧯 is not a Mojo🔥 project!

It is a project for Mojo🔥 projects.

<br />

Modo🧯 is a DocGen for Mojo🔥, written in <i class="fa-brands fa-golang" style="font-size: 200%; position: relative; top: 12px; color: #00ADD8;"></i>

---

## Why I built Modo🧯

### <big>↓</big>

----

No standard tool for API docs so far

Need API docs for first(?) Mojo🔥 ECS: [Larecs](https://github.com/samufi/larecs)

Want simple, low-tech, generic solution

---

## What it does

### <big>↓</big>

----

Using `mojo doc` JSON...

- creates Markdown files suitable for SSGs

- converts code examples to unit tests

- can run the whole chain with a single command

---

## Demo

### <big>↓</big>

----

Clone a random Mojo🔥 project

```bash
# use a fresh directory
mkdir demo; cd demo
# clone EmberJson
git clone https://github.com/bgreni/EmberJson.git
# cd into it
cd EmberJson
```

----

Set up a Modo🧯 project and build API docs

```bash
# initialize Modo project in Hugo format
modo init hugo
# build API docs for the project
modo build
# serve API docs with Hugo
hugo serve -s docs/site/
```

Open the displayed URL in a web browser

---

## Features

### <big>↓</big>

----

### Output formats

Several fully supported rendering target

<br />

Plain Markdown

<br />

[Hugo](https://gohugo.io)  
popular open-source SSG

</div>
<div class="col" style="margin-left: 2rem flex: 1;">

[mdBook](https://github.com/rust-lang/mdBook)  
known from the <i class="fa-brands fa-rust"></i>Rust book

</div>
</div>

<br />

Your wishes?

----

### Cross-references

Very simple syntax, resembling Mojo imports

```python
"""
Relative ref to [.Struct.method] in the current module.
"""
```

</div><div class="col" style="flex:0.1;"></div><div class="col">

Relative ref to [Struct.method]() in the current module.

</div></div></div>

<div><div class="columns"><div class="col">

```python
"""
Absolute ref to module [pkg.mod].
"""
```

</div><div class="col" style="flex:0.1;"></div><div class="col">

Absolute ref to module [mod]().

</div></div></div>

<div><div class="columns"><div class="col">

```python
"""
Ref with [pkg.mod custom text].
"""
```

</div><div class="col" style="flex:0.1;"></div><div class="col">

Ref with [custom text]().

</div></div></div>

----

### Re-exports

Re-structure docs the way users see your package

<br />

<pre style="width:100%; font-size: 0.65em;">
- mypkg
  - mod
    - Struct
  - subpkg
    - submod
      - Trait
</pre>

</div>
<div class="col" style="flex:0.2;">

#### <i class="fa-solid fa-arrow-right"></i>

</div>
<div class="col" style="flex:2.0;">

```python
"""
Package mypkg...
"""
from .mod import Struct
from .subpkg.submod import Trait
```

```python [4-6]
"""
Package mypkg...

Exports:
 - mod.Struct
 - subpkg.submod.Trait
"""
from .mod import Struct
from .subpkg.submod import Trait
```

</div>

</div>

</div>
<div class="col" style="flex:0.2">

#### <i class="fa-solid fa-arrow-right"></i>

</div>
<div class="col">

Modo🧯

<pre style="width:100%; font-size: 0.65em;">
- mypkg
  - Struct
  - Trait
</pre>

</div>
</div>

----

### Doc-tests

Convert code examples into unit tests

````python
"""
Doc-test example.

```mojo {doctest="sum"}
var a = 1 + 2
```

```mojo {doctest="sum" hide=true}
if a != 3:
    raise Error("failed")
```
"""
````

</div>
<div class="col" style="flex:0.4;">

#### <i class="fa-solid fa-arrow-right"></i>

</div>
<div class="col">

Doc-test example.

```python
var a = 1 + 2
```

`..._test.mojo`

```python
fn test_sum() raises:
    var a = 1 + 2
    if a != 3:
        raise Error("failed")
```

</div>
</div>
</div>

----

### Scripts

Configure pre- and post-processing bash scripts

```yaml
# Bash scripts to run before build as well as test.
pre-run:
  - |
    echo Running 'mojo doc'...
    magic run mojo doc -o docs/src/mypkg.json src/mypkg
    echo Done.
```

```yaml
# Bash scripts to run after test.
# Also runs after build if 'tests' is given.
post-test:
  - |
    echo Running 'mojo test'...
    magic run mojo test -I src docs/test
    echo Done.
```

----

### Templates

Customize Markdown output via templates

```template
Mojo struct

# `{{.Name}}`

{{template "summary" . -}}
{{template "description" . -}}
{{template "aliases" . -}}
{{template "parameters" . -}}
{{template "fields" . -}}
{{template "parent_traits" . -}}
{{template "methods" . -}}
```

---

## How to get Modo🧯

### <big>↓</big>

----

#### Python/pip

`pip install pymodo`

<br/>

#### Go

`go install github.com/mlange-42/modo`

<br/>

#### Pre-compiled binaries

GitHub Releases

---

## @Modular

### <big>↓</big>

----

#### Please...

<br />

Specify cross-ref syntax

Include package re-exports in JSON

Support Markdown lists in  `Raises` section

---

## Contributing

### <big>↓</big>

----

"Playtest"

Give feedback on tool and docs

Create issues & PRs

---

## Thank you!

[<i class="fa fa-github"></i>/mlange-42/modo](https://github.com/mlange-42/modo)