2 Contributing
This documentation is written and maintained in Quarto. A live version of the current documentation is available at GitHub. The live version of the documentation is rendered from the current main branch at https://github.com/pyani-plus/design-documentation, using GitHub Actions.
pyani-plus is an open source project and we welcome contributions using standard good development practice. This page outlines our local flavour of what we think of as “good practice.”
Please keep all documentation and examples, so far as is possible, in Quarto to minimise the effort required for maintanance.
If you are already comfortable with GitHub and Quarto, you might want to skip straight to the example workflow.
2.1 Obtaining the current documentation
To get a local copy of the documentation on your own machine, clone the repository to your own machine. For example, at the command-line you might issue:
git clone git@github.com:pyani-plus/design-documentation.gitwhich will create a new directory called design-documentation in the current location.
2.1.1 Project content layout
As is standard for Quarto projects, the top level - the same one with the Rproj file - contains a set of .qmd files - one for each page of the documentation. The ordering of these pages is determined by the chapters section in the _quarto.yml configuration file, not by filename.
Please keep all document pages in the top level of this repository.
The assets subdirectory is used to hold additional, non-.qmd files, such as images, each datatype contained within their own nested subfolder.
design-documentation
|
assets
|
data
|
images
|
papersdata- contains datafiles (e.g. example third-party program output).images- contains image filespapers- contains references and other material it’s useful to have accompany this documentation
Please organise all asset files under the assets subdirectory as outlined above
2.1.2 Project styling and configuration
Styling and configuration is controlled mainly by two YAML files: _quarto.yml and _variables.yml.
_quarto.yml- describes headers, footers, titles, page ordering, etc._variables.yml- describes variables that can be reused throughout the document
Please use the _variables.yml file where appropriate to define variables that may be reused at many points in the document, such as contact emails, paths repository features, and so on.
2.2 Editing the documentation
If you are working in the pyani-plus/ organisation the first action for editing or creating a new section should be to create a new branch with, e.g. git checkout -b issue_1.
If you are not working in the pyani-plus organisation you should be working in your own fork of the repository.
Before editing the documentation, please be sure that you are not working in the main branch. The main branch is locked for push actions, and attempts to push direct to main will fail. Please see the section on submitting changes below.
This documentation is written in Quarto and can, technically, be edited in any standard code editor (e.g. VS Code, Emacs or Vim). However, it may be most convenient to edit the project using RStudio Desktop, which has native Quarto and git/GitHub integration.
The repository is an RStudio project, which is defined in the design-docs.Rproj file (.Rproj files are the definition files for these projects). To open the project, either open the .Rproj file from within RStudio Desktop, or double-click the file in your file manager window. The project should open in RStudio Desktop, if it is installed.
2.3 Making suggestions
If you have spotted an error, or would like to suggest a change to the documentation, and cannot or do not want to make changes to the documentation yourself - or cannot make those changes immediately - please create an issue on the repository.
2.4 Example Workflow
This example workflow describes the actions required for a developer in the pyani-plus-dev team.
2.4.1 Clone the repository to your local machine
git clone git@github.com:pyani-plus/design-documentation.git2.4.2 Create a new branch
Use a short string that is informative for your changes, e.g.
git checkout -b issue_12.4.3 Make your edits
Update the documentation as you need to, checking that the documentation still builds by rendering it locally on your machine.
2.4.4 Rebase your local changes against main
In case changes have happened in the main branch, you should rebase your branch against the current state of main.
git fetch
git checkout my_branch
git rebase origin/mainThis replays your local changes on top of the current state of main on GitHub. Once this is done, please rerender to check that the documentation still builds.
2.4.5 Push the changes
Push the changes you made to the repository, e.g.
git push origin2.4.6 Make a pull request
Make a pull request against main from your new branch, at GitHub.
2.4.7 Participate in review
Making the pull request will prompt a code review. The changes might be accepted immediately without modification, after a delay, be modified, or require discussion in the pull request chat.