documentation_workflow.md

title	tags
GitHub Workflow	Documentation Contributing Examples

GitHub Workflow

1. Find an issue to resolve or create a new issue here.

2. Fork the documentation repo. If you're not familiar with forking see this guide.

3. Create an issue branch in your forked repo. For example, if the issue you're resolving is ISSUE-100:

   git checkout -b ISSUE-100

4. Copy this template to create a new piece of documentation:

   cp docs/documentation_template.md docs/new_documentation.md

5. Make your changes to the copied markdown file.

6. If this is new documentation add it to the nav section of the mkdocs.yml configuration file at the root of the repo. For example:

   nav:
     - Home: index.md
     - About Archipelago:
       - Archipelago's Philosophy & Guiding Principles: ourtake.md
       - Strawberryfields Forever: strawberryfields.md
       - Software Services: devops.md
       - New Documentation: new_documentation.md
     - Code of Conduct: CODE_OF_CONDUCT.md
     - Instructions and Guides:
       - Archipelago-Deployment:
         - Start: archipelago-deployment-readme.md
         - Installing Archipelago Drupal 9 on OSX (macOS): archipelago-deployment-osx.md
         - Installing Archipelago Drupal 9 on Ubuntu 18.04 or 20.04: archipelago-deployment-ubuntu.md
         - Installing Archipelago Drupal 9 on Windows 10/11: archipelago-deployment-windows.md
         - Adding Demo Archipelago Digital Objects (ADOs) to your Repository: archipelago-deployment-democontent.md
   ...

7. To view the changes locally, first install the Python libraries using the Python package manager pip:

   pip install mkdocs-material mike git+https://github.com/jldiaz/mkdocs-plugin-tags.git mkdocs-git-revision-date-localized-plugin mkdocs-glightbox

   You may need to install Python on your machine. Download Python or use your favorite operating system package manager such as Homebrew.

8. Now you can build the site locally, e.g. for the documentation using the 1.4.0 branch:

   mike deploy 1.4.0
   mike set-default 1.4.0

   If you create a new branch to match the issue number as in step 3, you would use your branch instead of 1.4.0. For example, a branch of ISSUE-129.

   mike deploy ISSUE-129
   mike set-default ISSUE-129

9. Start the web server:

   mike serve

10. Check the results in your browser by going to: http://localhost:8000

11. If everything looks good, you can push to your forked repo issue branch:

    git add .
    git commit -m "Create new docs with useful information."
    git push origin ISSUE-100

12. Create a pull request and link to the issue by tagging it, e.g. Resolves #100.