Repository Structure#

Sample OpenMDAO-Compatible Repository Template#

A lot of small details go into setting up a repository: the code itself, packaging mechanisms, continuous integration configuration, documentation building, and documentation styling, to name a few. To aid in the setup of a new tool built upon OpenMDAO, we have created a Github repository that is a basic template of how to set up your project. It is a small working example that you can clone and copy to help set up your own repository: OpenMDAO Library Template

Project Documentation Structure

First, to make things run smoothly, set up your project structure so that your documentation lies in the top-level project directory in a directory named /docs. For instance, “openmdao/docs” or “openaerostruct/docs”. The reasons for this location is this is where Jupyter Book will be looking for docs.

If you must put docs elsewhere for some reason, just be aware that it will require modifications to things in the above list.

Within /docs, you will have a lot of important files that will all interact to create your project docs:

  1. A _config.yml file, that configures your Jupyter Notebook. We have provided a modified example of ours in the repo. Jupyter Book will create this for you when you run jupyter-book build.

  2. An intro.md file, that is the top-level document in your entire project. You can rename this as long as you update the name in _toc.yml

  3. A README.md file, that gives instructions on how to build the docs.

  4. Directories of .md/.ipynb files that will be built.

Here’s an example of how all those things might look within the context of a real project, OpenMDAO:

internal_structure