Folder structure

Let’s start by showcasing the folder structure that we should aim for. Here is the folder structure of an example project, named simpleble (See GitHub repo and ReadTheDocs documentation), which is also the package which we will base our tutorial on:

├── docs
│ ├── build
│ ├── make.bat
│ ├── Makefile
│ └── source
├── requirements.txt
└── simpleble

In the folder structure above:

  • simpleble-master is the folder we get when we issue a git pull/clone command
  • simpleble-master/docs is the directory where our Sphinx documentation will reside
  • simpleble-master/docs/build and simpleble-master/docs/source being the Sphinx build and source directories respectively. These folders are autogenerated for us by Sphinx.
  • simpleble-master/simpleble is the actual Python package directory, where our Python source files reside.

An important note here is that the folder simpleble-master is what we will refer to as our Repository root, while the folder simpleble-master/docs will be our Sphinx root or, equivalently, our Documentation root. Similarly, simpleble-master/docs/source will be our Sphinx source root and simpleble-master/docs/build is our Sphinx build root.