Repository Structure

The Picard Documentation Project repository is partially structured both in terms of branches and directories and files. If you are submitting changes to the documentation then it is beneficial to understand the existing structure. In addition, it helps make it easier to locate a particular file when adding or correcting information.

---

Branch Structure

There are five types of branches within the repository:

1. Web Server Branch: This is the gh-pages branch, and it holds the files provided when the documentation is accessed at https://picard-docs.musicbrainz.org/. The content of this branch is updated automatically by an action script that is executed when changes are made to one of the Publication Branches. Typically, there will be no need to make changes to this branch manually via pushes or pull requests.

2. Publication Branches: These are the branches that will initiate a publish action when they are updated. These branches include release along with any version number branches named in the form {major}.{minor} where {major} and {minor} are integers containing only digits (e.g.: 2.5 or 3.0). A pull request entered against one of these branches will initiate a complete test build of all files from the branch, including all supported languages -- the same process as used for publishing except that the resulting files are not moved to the Web Server Branch. More information about how information is published can be found in the Publishing Logic wiki page. Once created, Publication Branches should not be removed.

3. Prerelease Branches: This includes all other branches whose names begin with a digit but do not meet the {major}.{minor} format of the Publication Branches (e.g.: 2.5.2 or 2.6b1). A push to, or a pull request entered against one of these branches will initiate a complete test build of all files from the branch, including all supported languages -- the same process as used for publishing except that the resulting files are not moved to the Web Server Branch. These Prerelease Branches can be created as required and removed when no longer needed. These are typically used to collect documentation changes for a pending release, and would be merged into the master branch once that version of Picard has been released.

4. Staging Branch: This is the master branch. This is used for staging of changes that will eventually be applied to the release Publication Branch. When the Staging Branch is updated, a check of the restructured text (RST) files is performed as well as a basic build of the publication files in the default language (English) only.

5. Working Branches: This includes all other branches which do not start with a digit. These will typically be used for development and staging of changes that will eventually be applied to the Staging Branch, or one of the Publication Branches or Prerelease Branches. When one of these Working Branches is updated, a check of the restructured text (RST) files is performed as well as a basic build of the publication files in the default language (English) only. These Working Branches can be created as required and removed when no longer needed, and can have any valid GitHub branch name except for the names reserved for the Web Server Branch, Staging Branch, Publication Branches and Prerelease Branches.

---

Directory and File Structure

There are generally two types of directory structures used -- one for the Web Server Branch and another for all of the source file branches (i.e. Publication Branches, Prerelease Branches and Working Branches).

Web Server Branch

The root directory of the Web Server Branch contains the files used to configure the operation of the web service for the site, as well as the publication script (publish.py) and its support files and templates. The root directory also contains the language-specific directories for the latest published content -- one directory for each supported language and named using the two-character code for the language contained (e.g.: en or fr).

The downloads directory contains the files that are available for download from the site, including the HTML file archives, PDF and EPUB files, and the tag mapping spreadsheet. The files available for download are linked from the Options section of the documentation pages, or can be accessed directly by browsing to https://picard-docs.musicbrainz.org/downloads/.

The remaining directories contain the version-specific published content, and are named by version number rolled up to the {major}.{minor} level such as v2.5 or v3.0. Each of these version-specific directories contains language-specific directories for the HTML content published for that version. The language-specific subdirectories are named using the two-character code for the language contained.

Source File Branches

The root directory of the Staging Branch, Publication Branches, Prerelease Branches and Working Branches contains the files used to configure the build environment for compiling the source files into the files to be published, as well as the script (setup.py) and support files used to perform the builds and miscellaneous maintenance of the project files.

The .github directory contains the action scripts for testing, building and publishing the files for the website, as well as the templates used by GitHub for things like pull requests and issue reports.

The _locale directory contains the gettext catalog files for translating the site to other languages. The translation template (*.pot) files produced by gettext are not included because they are recreated automatically when a build is initiated. The language-specific translation files are included and can be found in subdirectories named by the two-character language code. The individual language translation files are named with the .po extension.

The _static directory contains the static files such as css and site icon that are used throughout all versions and languages of the documentation provided on the website.

The _templates directory contains the templates used by Sphinx when building the documentation files.

All remaining directories contain the source files for the documentation, with each directory holding a specific chapter or topic. Images used for that chapter or topic are stored in an images subdirectory of the topic directory. Note that images to be used for languages other than the default (English) base language must have the two-character target language code identified just prior to the file extension. For example, if the English version of an image is named image1.jpg, the French version of the image would be image1.fr.jpg. If there is no language-specific image file, then the default (English) image file will be used. The image would still be specified using the default (English) name in the restructured-text files, and Sphinx would automatically use the French version if available for the French version of the documentation.

The documentation files are developed using restructured-text and are named with the extension .rst. The top-level index files are stored in the root directory for HTML (index.rst), PDF (pdf.rst) and EPUB (epub.rst) output.

---