Skip to content

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
mkdir projects
cd projects
git clone https://github.com/dmccreary/microsims

After Changes

After you make local changes you must do the following:

1
2
3
4
5
6
# add the new files to a a local commit transaction
git add FILES
# Execute the a local commit with a message about what and why you are doing the commit
git commit -m "comment"
# Update the central GitHub repository
git push

Material Theme

We had several options when picking a mkdocs theme:

  1. Mkdocs default
  2. Readthedocs
  3. 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
conda deactivate
conda create -n mkdocs python=3
conda activate mkdocs
pip install mkdocs "mkdocs-material[imaging]"

Mkdocs Commands

There are three simple mkdoc commands we use.

Local Build

1
mkdocs build

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
mkdocs serve

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
mkdoc gh-deploy

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.

  1. 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.
  2. 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
brew install cairo freetype libffi libjpeg libpng zlib

I then had to add the following to my ~/.zshrc file:

1
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib

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.