The Sensel Documentation is made using the mkdocs framework. It's a great framework for writing documentation in markdown then rendering it into HTML for the web. There are various themes available for customizing the look and feel. We are using a fork of mkdocs-material theme for these documents, which provides a Google material-like layout that is responsive and attractive.
If you find an error or improvement, feel free to log an issue. Even better, you can clone, correct, and make a pull-request on this repo.
If you are not familiar with formatting text in "markdown", here is a good cheatsheet.
What's In This Repo
- docs - markdown files and images that make the documentation
- overrides - override css and partial html files, generated from
- mkdocs.yml - configuration file for generating the documentation site
Current setup on macOS is using Python 3.9.2 and mkdocs 1.1.2. You will want to make sure you are using python 3 by default.
You will need git installed, of course
When installing in Windows, make sure you have the bash option checked:
On Windows, I'd recommend you install PowerShell.
You'll need to install Python 3. You may want to scrub your system of other versions of python, unless you need them. To delete other versions, you might find it in multiple places. Delete each:
- C:\Python 2.7\
- C:\Users<you name>\AppData\Local\Microsoft\WindowsApps\python.exe
- C:\Users<you name>\AppData\Local\Microsoft\WindowsApps\python3.exe
Using Mac Terminal or Windows PowerShell, make sure you have mkdocs installed. This uses version 1.0 or greater.
pip install mkdocs
You also need the material theme installed:
pip install mkdocs-material
Modify and Edit
Clone the repo for these docs:
git clone https://github.com/sensel/morph-docs.git
mkdocs.yml provides values for many of the parameters for building the docs. More info is in the mkdocs documentation.
docs folder has all the markdown files and images that populate the content of the documentation. This is where all of the editing and changes happen. If you want to see the changes in a browser preview, you can run
from the root of this repo.
The only files you need to edit are the
mkdocs.yml file and files in the
To modify the theme, you can just modify the files in the
overrides folder in the morph-docs repo. Simple changes to css and layout can be quickly accomplished.
Read the mkdocs-material documenation for more info.
NOTE: This is documented for Sensel - it's not something that needs to be done by the generous user who is making a pull-request for a fix or addition to the docs!
1.) Update Docs (if modified)
Make changes to the markdown (.md) files in docs/ and add any images you need. Preview your changes locally with
and visit the local page in your browser.
2.) Publish Docs
Once changes have been made to the documentation, from the root of this repo, run
There is a command
that will automate this, but it might require some tinkering to use the github personal access tokens, since password authentication was removed in August 2021. If you are lucky, you'll be asked to authenticate through the browser.
mkdocs gh-deploy is borked, then you'll just need to push the build manually to the ghpages branch. Use
mkdocs-build to create the site. This makes a
site/ folder in the morph-docs folder that you will want to move to someplace temporary, like your desktop. Then switch branches to
gh-pages and copy-and-replace the contents of the
site folder to the
morph-docs folder. Then commit the changes and push to the gh-pages repo.
Addendum: API Documentation.
This is more for Sensel's internal use. There are no secrets here, but it's not something germane to the github public. However, this is a good place to document things, so here goes.
Documentation for the raw API calls is generated using headerdoc. This pulls documentation from the source code, and converts it to html. The html files can be minimally processed with a shell script, resulting in files that can be included in the published guide.
First, generate html from the
sensel_decompress.h files into the directory
headerdoc2html -o sensel-html sensel.h sensel_decompress.h cd sensel-html gatherheaderdoc .
Now, copy the
clean_headerdoc.sh from this repo into the
sensel-html directory. You can now run
./clean_headerdoc.sh sensel_h/index.html ./sensel_h.html ./clean_headerdoc.sh sensel_decompress_h/index.html ./sensel_decompress_h.html
to remove everything that's not in
<body></body> and clean up the html a bit.
You are now ready to move the