-
Couldn't load subscription status.
- Fork 0
Implementation Considerations
This page is intended to capture the considerations for implementing the concepts and changes in this repository into the metabrainz/picard-docs repository and replace the Picard on-line documentation platform from the current GitHub Pages (GHP) to ReadTheDocs (RTD). Prior to proceeding, it is important that there is agreement from the involved parties regarding the structure and use of this repository for the documentation, as currently available via the temporary RTD link https://rds-picard-docs-restructure.readthedocs.io/.
The metabrainz/picard-docs repository is owned by metabrainz and should remain as such. The changes from this temporary restructuring archive should be merged into the existing picard-docs repository.
The associated projects (main project and translations) for the documentation on RTD should be owned by metabrainz with the appropriate personnel added as maintainers. Ideally, the main project will be named picard-docs if the project name is available on RTD.
- Question: Does metabrainz have an account on RTD, and if so who has access to the account?
The translations will continue to be managed using Weblate via the https://translations.metabrainz.org/projects/picard-docs/ server. The translation files are maintained in the same directory structure as the current picard-docs repository, so there should be no configuration changes required for Weblate.
Note that in addition to reconfiguring the repository for publication on the RTD platform, there have been considerable changes made to the source RestructuredText (RST) files, including removal of all unnecessary newlines and extra spaces between sentences. This latter change impacts the translation files, so an attempt has been made to make the corrections to any translation (PO) files impacted in the hopes of minimizing the work required by the translators on Weblate.
The current repository has the documentation published for all released {major}.{minor} versions beginning with v2.11. The updated repository will retain the same {major}.{minor} versioning scheme, but will begin with the v2.13 release (dropping v2.11 and v2.12). The reason for this is to reduce the effort required by not having to convert older versions that should no longer be in use.
In addition to the numbered versions, RTD will publish the master branch of the repository as the latest version (with a popup warning that some of the functionality may not yet be available in the current release of Picard), and the highest numbered version as the stable version.
In addition to the documentation website, RTD is currently configured to provide the documentation in the form of a PDF file for download. The ePub download option has currently been disabled due to issues with generating a properly formatted output file.
- Question: Do we want to keep the v2.11 and v2.12 versions of the documentation and publish them on RTD?
- Question: Do we really need an ePub file in addition to the PDF file? The PDF file should be sufficient for off-line reference.
The current documentation is available via redirection of https://picard-docs.musicbrainz.org to the appropriate GitHub Pages URL. Once the documentation is available on the RTD server, the picard-docs URL should be redirected to the RTD server, and the gh-pages and release branches removed from the repository (along with the code and configuration settings that generate the content of the gh-pages branch).
The documentation links currently generated by Picard should be properly displayed on the RTD site through special redirection coding included in a special 404/Page Not Found file. In order to reduce the redirection processing on RTD, the URL generation in Picard should be updated to match the RTD URL structure of /{language}/{version}/{path and page} with the {language} portion defaulting to en because that is the base language for the documentation (and the only language guaranteed to be available), and the {version} in the form v{major}.{minor} (leaving off any point or beta/pre-release identifiers). In the case of beta or pre-release versions, the {version} should be set to latest.
The documentation for the repository (including the Wiki) will need to be updated to reflect the changes to the updating and publication processes. This includes Contributor notes and adding the dev_tools.py documentation to the Wiki.
The automation provided through the GitHub Actions configuration files will need to be updated to reflect the changes to the updating and publication processes. This includes CI testing for pull requests and merging, as well as any references to publishing in the gh-pages branch. Publication on RTD is configured in the .readthedocs.yaml file in the root directory of the branches.
Following are the proposed steps for implementing the Picard User Guide publication on ReadTheDocs:
Responsible: zas, outsidecontext, rdswift (as a minimum)
Review the test implementation repository publication results at https://rds-picard-docs-restructure.readthedocs.io/} and confirm that they are acceptable. This should include confirmation by at least zas, outsidecontext and rdswift.
Responsible: rdswift
The automation provided by GitHub Actions on the metabrainz/picard-docs repository should be modified to disable any publishing to GitHub Pages.
Responsible: rdswift
The master branch on the metabrainz/picard-docs repository should be updated to match the master branch on the rdswift/picard-docs-restructure repository. The new branches next_version and v2.13 (plus v2.12 and v2.11 if we decide to include them) should be added to the metabrainz/picard-docs repository from the rdswift/picard-docs-restructure repository.
In addition to the updated documentation, configuration and translation files, the changes / additions should include the new .readthedocs.yaml file, the updated (and renamed) dev_tools.py file, and any GitHub Actions and automation changes currently building or publishing the documentation.
Responsible: rdswift, outsidecontext
The changes to the translation files in the master branch should be picked up automatically by Weblate when the master branch is updated in the previous step. This should be confirmed and, if it has not happened, the project in Weblate should be updated/reset to ensure that it is synchronized with the updated metabrainz/picard-docs repository.
Responsible: rdswift (or owner of the metabrainz account on RTD)
The main and translation projects should be set up on ReadTheDocs. Ideally the primary project name should be picard-docs. The projects should include, as a minimum zas, outsidecontext and rdswift as maintainers.
Responsible: rdswift
If the documentation was not automatically built on ReadTheDocs in the previous step, the builds should be triggered manually. Confirm that the resulting documentation site is working as expected.
Responsible: zas (coordinate with rdswift?)
Update the picard-docs.musicbrainz.org domain to point to the repository on ReadTheDocs. The steps required for this process are generally covered in https://docs.readthedocs.com/platform/latest/guides/custom-domains.html.
Responsible: zas, outsidecontext, rdswift (as a minimum)
Confirm that the documentation is being served properly from the ReadTheDocs server via the picard-docs.musicbrainz.org url. Also confirm that opening the documentation from within Picard works as expected.
Responsible: rdswift
The documentation should be removed from the GitHub Pages server by removing the gh-pages branch on the metabrainz/picard-docs repository. Ensure that all references to building and publishing the documentation in this branch (such as GitHub Actions and associated scripts) are also removed from the repository.
Responsible: rdswift, PR authors
Outdated version branches such as 2.11, 2.12, 2.13 and version_3_changes (superceded by v2.11, v2.12, v2.13 and next_version respectively) should be removed from the metabrainz/picard-docs repository. Outstanding pull requests should be redirected to the new branches as appropriate.
Note that the pull requests may need to be redirected before the outdated branches are removed. Ensuring that the pull requests are properly directed and rebased may require significant effort.
Update the Wiki pages to reflect the revised processing, and add a new page documenting the dev_utils.py utilities added.
Responsible: rdswift (code almost ready to submit)
It is recommended that Picard be modified to ensure that the references to the documentation follow the standard ReadTheDocs URL path naming scheme (i.e. /{language}/{version}/{path and page}). Stable versions of Picard could point to the appropriate version on RTD (e.g. v2.13), while pre-release versions (e.g. alpha or beta) could point to the latest version on RTD. Perhaps Picard could make a call to the ReadTheDocs API during startup to determine if the version and/or the user's selected language/locale are available and adjust the documentation links accordingly to display the appropriate documentation page (language and version) if available with an appropriate fallback such as the default language and latest or stable version.