Doc Building and Synchronization

[Oglopf]

There are more than one way to build the docs currently. Using either docker or pipenv and in either case, there are different images being used on docker-hub, which means there is a possibility of divergence in state between them and one method working while another is broken.

This ticket is to propose either of the following:

• cutting out the multiple build paths and agreeing on a single path
• come up with a plan to keep these differing build paths and images they need in sync

Either of these would be fine and the issue is nothing major, but it is some technical debt that seems easy to pay down with some discussion.

The docker method uses rake docker:build which relies on:

namespace :docker do

  desc "Build docs using docker"
  task :build do
    exec 'docker run --rm -i -t -v "${PWD}:/doc" -u "$(id -u):$(id -g)" ohiosupercomputer/docker-sphinx make html'
  end
end

Using the pipenv method ends up relying on the make utility and the repo's makefile which looks to use the sphinx-build command in the environment it sets up, and so from my reading it doesn't look like any docker-hub image is used, but I've also not looked at makefiles much.

In any case, it would be best to somehow get these synced by ensuring they use the same image to build and work on or removing one entirely.

┆Issue is synchronized with this Asana task by Unito