File Structure for NWChemEx Repositories
To the extent possible, we want all NWChemEx repositories to follow the same file structure. Since each repo in the organization is ultimately different, it will in general not be possible for every repo to be laid out exactly the same; however, we strive to only deviate from the standard layout when absolutely necessary.
Why Do We Need to Standardize the Repository Layouts?
Admittedly, the repository layout adopted by all repositories in the NWChemEx organization was chosen based on personal preference of the lead developers. However, now that a standard has been agreed upon it is important that we adhere to it. In particular, by standardizing the file layout of each repo we are able to facilitate:
Confidence. Well laid out repositories instill a more professional impression on anyone viewing the repository’s files.
Finding files. Users/developers familiar with the layout of one NWChemEx repository can quickly and easily find files in another.
Automation. If all the repositories are laid out the same it is much easier for CI/CD to maintain them.
On-boarding new developers. Where possible our layouts adhere to wider file system standards, standards which are familiar to many developers outside the NWChemEx organization. By adhering to such standard we lower the barrier to entry for new developers.
Files and Directories
In this section we provide a top-down tour of a typical NWChemEx repository’s file structure.
Root Level
At the root level, most (although it should ideally be all) repositories in the
NWChemEx organization conform to the layout shown in
Fig. 7. As a quick internet search will show (see for
example here) this layout is fairly standard, albeit
universal. We note that using our layout, the only files residing at the
root-level of the repository are there either because they must live at the
root-level (e.g., .clang-format
), or are present at the root-level to
emphasize they apply repository wide (e.g., LICENSE
).
Note
A notable (well explained) argument against our chosen layout can be found here.
.github Directory
Fig. 8 shows the layout of the .github/
directory in
nearly every repository owned by the NWChemEx organization. The layout
and naming conventions are dictated by GitHub and are thus commonly found in
most GitHub projects.
docs/ Directory
The set-up of the directory is driven by Sphinx, which by default assumes all
documentation source lives in root/docs/source/
, the configuration file for
Sphinx resides at root/docs/source/conf.py
, and automatically creates the
root/docs/Makefile
file to facilitate building the documentation. The
remaining files, root/docs/requirements.txt
and root/docs/README.md
are
to respectively facilitate obtaining the dependencies of the documentation and
to instruct the reader on how to build the documentation.