How We Built This Site
This page describes how we built this website and some of the rationale behind why we made various design choices.
Python
MicroSims are about how we use generative AI to create animations and simulations. The language of AI is Python. So we wanted to create a site that could be easily understood by Python developers.
Mkdocs vs. Docusaurus
There are two main tools used by Python developers to write documentation: Mkdocs and Docusaurus. Mkdocs is easier to use and more popular than Docusaurus. Docusaurus is also optimized for single-page applications. Mkdocs also has an extensive library of themes and plugins. None of us are experts in JavaScript or React. Based on our ChatGPT Analysis of the Tradeoffs we chose mkdocs for this site management.
GitHub and GitHub Pages
GitHub is a logical choice to store our site source code and documentation. GitHub also has a Custom GitHub Action that does auto-deployment if any files on the site change. We don't currently have this action enabled, but other teams can use this feature if they don't have the ability to do a local build with mkdocs.
GitHub also has Issues, Projects and releases that we can use to manage our bugs and tasks.
The best practice for low-cost websites that have public-only
content is GitHub Pages.
Mkdocs has a command (mkdocs gh-deploy
) that does
deployment directly to GitHub Pages. This was an easy choice to make.
GitHub Clone
If you would like to clone this repository, here are the commands:
1 2 3 |
|
After Changes
After you make local changes you must do the following:
1 2 3 4 5 6 |
|
Material Theme
We had several options when picking a mkdocs theme:
- Mkdocs default
- Readthedocs
- Third-Party Themes See Ranking
The Material Theme had 16K stars. No other theme had over a few hundred. This was also an easy design decision.
One key criterial was the social Open Graph tags so that when our users post a link to a simulation, the image of the simulation is included in the link. Since Material supported this, we used the Material theme. You can see our ChatGPT Design Decision Analysis if you want to check our decision process.
Conda vs VENV
There are two choices for virtual environments. We can use the native Python venv or use Conda. venv is simle but is only designed for pure Python projects. We imagine that this site could use JavaScript and other langauges in the future, so we picked Conda. There is nothing on this microsite that prevents you from using one or the other. See the ChatGPT Analysis Here.
Here is the conda script that we ran to create a new mkdocs environment that also supports the material social imaging libraries.
1 2 3 4 |
|
Mkdocs Commands
There are three simple mkdoc commands we use.
Local Build
1 |
|
This builds your website in a folder called site
. Use
this to test that the mkdocs.yml site is working and does not
have any errors.
Run a Local Server
1 |
|
This runs a server on http://localhost:8000
.
Use this to test the display formatting locally
before you push your code up to the GitHub repo.
1 |
|
This pushes everything up to the GitHub Pages site. Note that it does not commit your code to GitHub.
Mkdocs Material Social Tags
We are using the Material Social tags. This is a work in progress!
Here is what we have learned.
- There are extensive image processing libraries that can't be installed with just pip. You will need to run a tool like brew on the Mac to get the libraries installed.
- Even after
brew
installs the libraries, you have to get your environment to find the libraries. The only way I could get that to work was to set up a local UNIX environment variable.
Here is the brew command that I ran:
1 |
|
I then had to add the following to my ~/.zshrc file:
1 |
|
Note that I am running on a Mac with Apple silicon. This means that the image libraries that brew downloads must be specific to the Mac Arm instruction set.