Good documentation is key to a good software and at Cheshire Cat AI we are always looking for great community members that are willing to improve it with their writing skills. This README as well as all the documentation you can find about the Cat is the result of an effort between our Core team and a great Community. Remember to always have fun whatever you decide to contribute to, meow.
/mkdocs
directory./assets
folder for your static assets. Eg. Images goes under /assets/img
.mkdocs.yml
file if you have made any structural modifications.There is a dedicated channel for Docs on our official Discord, don't be shy and contact us there if you need help!
To help documenting the hooks table, ensure these elements are not missing and please keep the order:
warning
box/additional info
for tips, tricks and discouraged behaviors (!!! info
/!!! warning
)??? example
)??? note "Other resources"
--> in this section please include the link to the hook Python reference in the documentation and any other useful links to other doc's pages.Example:
1. **Input arguments**
`user_message_json`, i.e. the JSON message sent via WebSocket done like this:
```JSON
{
"text": # user's message here
}
!!! info
Hook the incoming user message JSON dictionary
??? example
```python
from cat.mad_hatter.decorators import hook
@hook # default priority = 1
def before_cat_reads_message(user_message_json, cat):
user_message_json["text"] = "The original message has been replaced"
cat.working_memory["hacked"] = True
return user_message_json
```
??? note "Other resources"
- [Python reference]()
## ๐คน Manage the tecnology [mkdocs]
To modify the behavior of MkDocs and its plugins, everything you need is within the `mkdocs.yml` file.
We invite you to read the documentation for the [MkDocs Material theme](https://squidfunk.github.io/mkdocs-material/reference/) to fully understand all the potential of the tool and how to make the most of its extensive features.
### ๐ฆ Requirements
- Python 3.8+
- Pip 20+
Install dependencies:
`pip install -r requirements.txt`
### ๐ ๏ธ Develop
`mkdocs serve` or `python -m mkdocs serve` will launch a local, non static, instance of the documentation website.
### ๐๏ธ Diagrams
All the diagrams under the "Framework/Technical Diagrams" section have been created using draw.io.
The file [drawio-cheshire-cat-library](drawio-cheshire-cat-library.xml) is a draw.io library, it contains some custom Cat shapes, this library has been created to speed up the sketching, you can use it opening the file with draw.io.
You can refer to the draw.io files with the extension `.drawio`, directly from the markdown files like this:
```mk
# 😼 The Cat Bootstrap
This interactive diagram, zoomable with a click, depicts the internal process involved during bootstrap of the Cat:
![](../../assets/diagrams/cat-bootstrap.drawio)
In the mkdocs.yml
there is defined the hook drawio_file.py
, this mkdocs plugin converts the drawio files during the build time:
hooks:
- mkdocs/hooks/drawio_file.py
Remember that:
the tab selected during the save of the draw.io file, will become the initial page when the diagram is opened
the layers visible during the save of the draw.io files, will be the default visible layers when the diagram is opened
by default, the hooks shapes have to be visible
the folder mkdocs/assets/img/diagrams
contains the svg files used in the main diagram pages, in case you change the diagrams remember to update them.
The build stage is automated using GitHub action, you don't need to do it in order to contribute. However, if you want to have a static copy of the documentation on your local machine you are free to do it.
mkdocs build
or python -m mkdocs build
will create the actual docs static website in a folder named /docs
.