MkDocs¶
We are using MkDocs to generate our documentation. See Docker-mkdocs repo for information about MkDocs and the image we're using.
Work on docs locally¶
The first time starting the container may take longer due to downloading the ~40MB docker image
-
Run the mkdocs container.
- Optionally use the
-d
flag to run the container in the background
- Optionally use the
-
Open a browser to
http://localhost:8005/
to view the documentation locally. -
Modify the files in the
docs
directory. The site will auto-update when the files are saved. -
Ctrl+C to quit the local server and stop the container
Auto-generated docs¶
We have a GitHub Action set up to generate and host the documentation on a GitHub Pages site
MkDocs syntax¶
We're using Material for MkDocs. Aside from standard markdown syntax, there are some MkDocs and Material-specific syntax which can help more effective documentation. See the Material reference docs for the complete set of syntax.
Here's a list of commonly used MkDocs syntax for quick reference.
Code Blocks¶
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
list_display = (
"name",
"start_time",
"duration_in_min",
)
Numbered Lines | |
---|---|
```python title="Code Block"
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
list_display = (
"name",
"start_time",
"duration_in_min",
)
```
```python title="Numbered Lines" linenums="1"
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
list_display = (
"name",
"start_time",
"duration_in_min",
)
```
```python title="Highlighted Lines" hl_lines="1 3 5"
@admin.register(RecurringEvent)
class RecurringEventAdmin(admin.ModelAdmin):
list_display = (
"name",
"start_time",
"duration_in_min",
)
```