Repository Structure

Repository Structure (DRAFT)

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 three types of branches within the repository:

1. Web Server Branch: This is the gh-pages branch, and it hold 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 master along with any version number branches named in the form {major}.{minor}[.{micro}] where {major}, {minor} and {micro} are integers containing only digits (e.g.: 2.3.2, 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. Working Branches: This includes all other branches which will typically be used for development and staging of changes that will eventually be applied to one of the Publication 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 and Publication 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 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 such as v2.5.1 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 Publication 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 files are in the gettext subdirectory, and the language-specific translation files are in directories named by the two-character language code. Translation template catalogue files are named with the .pot extension, and 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.

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.