FabAcademy 2020 - Nicolas Lefebvre

This first week was dedicated to two tasks:

  • setting up our personal documentation websites
  • sketching our an idea for our final project

# Personal websites

# Understanding the provided template

The pre-built repos for websites already make a couple of very reasonable choices:

This is plenty good enough, and is simple, which is an often overlooked key property of a software solution to a problem!

In practice, to work with the provided template locally:

  • clone your repo
  • install Python
  • install MkDocs: pip install MkDocs
  • install the theme used by the same site: pip install MkDocs-material
  • run the development server: MkDocs serve
  • got to http://localhost:8000/

# Replacing the provided template

That being said, I wouldn't be a software engineer if I didn't immediately want more customization than what MkDocs can offer, so off to search for a more modern static site generator I went. In particular, I'd like a system that is still simple enough to use but also extensible enough to add custom code to my pages down the line if needed, plug in new features like UML integration (specifically PlantUML), support progressive image loading, etc.

I tried two solutions that seemed to fit the bill:

Both of the rely on Vue.js, a Javascript framework that I only have limited exposure to but that has a philosophy I like (briefly: a progressively adoptable framework rather than a monolithic "use us for everything right now" approach).

Gridsome looks amazing, and probably is. It is also way, way too much effort and customization for this project, as I realized four hours into trying to understand its complex routing system, its plugin ecosystem, and the GraphQL query language it uses. As a web developer, I've been meaning to learn GraphQL, but under a short deadline to produce a website as the pre-requisite to all of the actual work we'll have to do for this course, it's a little too much.

Thankfully, the Gridsome documentation is pretty great, including an honest and well written "what else could I use?" section that helpfully pointed me to Vuepress.

Vuepress turned out to be the "just right" solution for me for this project: it looks incredibly customizable, but it also makes enough choices I'm okay with out of the box (data comes from Markdown files instead of having to build a complex system of source plugins and GraphQL queries) to get started quickly.

In practice, replacing the provided template with Vuepress is pretty simple:

  • remove all of the contents of your repo
  • install Node.js
  • initialize a Node project (npm init)
  • install Vuepress as a dev dependency (npm install --save-dev vuepress)
  • create some content
  • run the dev server (vuepress dev docs)
  • create a new CI configuration file to deploy to Gitlab Pages

# Issues encountered and solutions

Getting Vuepress to generate a nice sidebar dynamically was a little more complex than expected. The trick here was to realize that it expects the top level sidebar navigation to be essentially static and set in config.js, while it will dynamically generate the sidebar content for each Markdown document within these static sections.

In other words:

themeConfig: {
        // ...
        sidebar: [
          '/assignments/week01',
          '/assignments/week02'
        ],
    }

will generate the sidebar you're seeing right now; the second and third level headings inside the Principles and practices section to your left are automatically generated (don't forget to add sidebarDepth: 2 to your front matter in your Markdown file to get the h3 level to show up).

This could / should be replaced with dynamically generating the array above by globing week*.md files from docs/assignements/, obviously. That will be left for the next time config.js needs an update!

WARNING

Windows specific (apparently?) pitfall here: changes to config.js do not trigger hot reloading; in fact, it is even necessary to kill the Vuepress dev server and restart it. This appears to be an open issue.

# CI/CD configuration for VuePress

As mentioned above, VuePress will need a different CI/CD pipeline to deploy to Gitlab Pages. This is thankfully documented in the VuePress doc, and pretty trivial anyway:

image: node:12.14.1

pages:
  cache:
    paths:
    - node_modules/

  script:
  - npm install
  - npm run docs:build
  artifacts:
    paths:
    - public
  only:
  - master

# Source Control and Git learning

This week was also, in theory, dedicated to learning Git, but this is an area where I was already pretty proficient. So for this week, here are instead some good resources to help others!

(shamelessly stolen from the internal Git documentation I maintain for Solidworks)

Recommended tutorials:

In addition to these, always remember that:

  • git help <cmd> will open the official reference for that command (usually quite verbose and technical)
  • git status will tell you what state your workspace is in, with suggestions for things you might want to do

Also, you may want to read about and use git lola. It will make understanding the state of your repository from the CLI much easier.

# Ideation for the final project

For the sake of readability, the weekly log for this task can be found in the final project page.

Computer Aided Design →