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.
/docs, you will have a lot of important files that will all interact to create your project docs:
_config.ymlfile, 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
intro.mdfile, that is the top-level document in your entire project. You can rename this as long as you update the name in
README.mdfile, that gives instructions on how to build the docs.
.ipynbfiles that will be built.
Here’s an example of how all those things might look within the context of a real project, OpenMDAO: