/temporary-sandbox-public

Temporary sandbox repo to test Github Actions and public contibutions

Primary LanguagePython

Piccadilly Circus Games Competition Website

Getting started

Some change

Setup

Usage

Run devenv shell in the terminal to enter a Bash shell with all dependencies installed. Alternatively, use direnv to manage this automatically.

once in the devenv shell the following usage can be executed.

Usage:

  • Run quarto render to render the site to the docs/ folder
  • Run quarto preview to serve the site in Quarto's local webserver
  • Review the _quarto.yml file and Github Actions workflow for more details

Generating API reference documentation

The repository includes an API documentation generator that takes documentation comments from Autonity protocol contracts and converts them into Markdown files.

TL/DR: Symlink an autonity repository clone into the root of this repository and run apidocgen. The configuration is in apidoc.toml.

Setup

  • Either clone the Autonity Go Client into the root of this repository
  • Or add a symlink to an existing clone into this repository with ln -s /path/to/autonity

Adding API documentation for a new Autonity release

  1. If there are new contracts to document, add them to apidoc.toml. The configuration is documented here.
  2. Switch to the release tag in Autonity, e.g. for v0.15.0: 
    cd autonity
git checkout v0.15.0
  3. Compile the protocol contracts: 
    make contracts
  4. Generate the API reference documentation: 
    cd -
apidocgen
  5. Review and commit the created Markdown files.

Note

Old Autonity branches (releases <= v0.14.1) do not build NatSpec data files. To generate API documentation for these branches, run patch-autonity in the root of this repository before step 3 to apply a patch to autonity/Makefile that modifies solc compiler options.

Developing contract documentation

Autonity protocol contracts are documented via documentation comments in Solidity source code. To help with previewing documentation, a script is available that watches the source directory in Autonity and rebuilds the documentation when files change.

  1. Launch the monitoring script with apidocmon.
  2. Open the preview URL from the terminal in the browser.
  3. Open Solidity code from the symlinked Autonity repository clone in a text editor and make changes. The browser window should reload with the new content.

Migrating from Hugo

For best results, clone into a new directory. However, if you are unable to do that, Delete the following directories as they will conflict and prevent Quarto from building:

 - themes/     # contains docys shortcodes
 - archetypes/ # contains docsy shortcodes
 - layouts/    # contains Markup for docsy templating
 - data/       # is empty and no longer required
 - docs/       # holds the content in a format that works for Hugo (and not Quarto).
 - content/    # holds the content in a format that works for Hugo (and not Quarto).

Publication workflow

The repo is configured to publish:

Development workflow

  • The master branch will always contain the live production version of the website.
  • The develop branch will be used for ongoing development and feature testing. All changes should be pushed to develop first, where they can be tested on a staging server before being merged into master.
  • Hot-fixes to the production site should be handled by creating a branch from master, implementing the fix, and creating a PR. Once the hot-fix is merged, master should be merged into develop to ensure the fix is propagated and conflicts are resolved.
  • A new version of the production website is published by merging develop into master after thorough testing.

The staging site is available here. The staging site is updated automatically on every push to the staging branch.

See the repo Wiki Page Git Workflow for when to merge or rebase branches when working on game.autonity.org repo.

Other Piccadilly site resources

For overall site structure, see Autonity Sitemap

Contributing

To contribute to this repo, please raise a pull request as per Github Flow.

Note that in order to maintain a legible Git history, this repo enforces linear history on master. To ensure that your local Git commit log is linear, you should rebase your local changes on top of origin. You can tell Git to do this for this repository by setting the Git option pull.rebase in your local checkout:

git config --local pull.rebase true

Alternatively, you can apply this setting for all your repos by replacing --local with --global.

Reference: Pro Git by Scott Chacon