Pushkin's documentation
Overview
Pushkin's documentation practices have been heavily influenced by jsPsych (thanks for the inspiration!). The docs use Material for MkDocs. You can find the documentation files in the /docs directory of the Pushkin GitHub repo.
Local testing
Since the docs are written in Markdown, the simplest of changes (e.g., typos) may not require a local build for testing purposes; the Markdown preview in your IDE may be sufficient. However, for anything substantive, you'll want to build and view the site locally to test your changes. After making changes in your development branch/fork, follow the steps below to test the site.
Install Poetry
MkDocs requires Python, which we'll assume you already have. Poetry is a package manager for Python. Building the Pushkin documentation doesn't necessarily require Poetry, but it makes it easier to install the docs' dependencies and guarantees the consistency of the build across contributors.
The easiest way to install Poetry is with pipx. If you need to install pipx, follow their installation instructions. Then, all you need to do is run:
For details, see Poetry's installation instructions.
Install dependencies and build the docs
In the root of the repo, run either:
or
Note
The former command is simply shorthand for the latter, but the former may not work if you haven't first run yarn install in the process of making your changes. This is not necessarily true if you're just fixing an issue in the docs themselves.
For the most faithful representation of what the docs site would look like with your changes, you should substitute <docs_version> with the major/minor version number (i.e. X.X) of pushkin-cli; however, getting the version number right isn't particularly important if all you're doing is local testing. It will simply change whether you overwrite an existing version of the docs or create a new one in your local gh-pages branch. It will not affect the public deployment of the docs.
Including the latest alias in your command is helpful, since the docs website defaults to the version tagged latest. This way, when you preview your edits, the version you deployed will pop right up when you visit http://localhost:8000/ (see below).
This command builds the docs and commits the new or updated version to your local gh-pages branch. Note that you will not be able to push any of these commits to remote unless you are a core Pushkin maintainer, as doing so would affect the public deployment of the docs site. Of course, you can still push your commits editing the source files to whatever development branch/fork you like before making a pull request.
Preview the docs
In the root of the repo, run either:
or (1)
- As above,
yarn docs:servemay require previously runningyarn install.
You should now be able to view the docs at http://localhost:8000.
Tip
Each time you build the docs, mike automatically commits to your local gh-pages branch. If you're doing local testing as you compose updates to the docs, you will be left with a bunch of junk commits that you might want to delete. To delete them, run:
This will reset your local gh-pages branch to the remote state (i.e. whatever is currently deployed on the live site). Make certain you've checked out gh-pages before running the reset command, as you don't want to accidentally reset your actual development branch.
Public deployment
Warning
Only core Pushkin maintainers have permissions to push to gh-pages.
As mentioned above, building the docs locally will automatically commit to gh-pages. Pushing these commits will update the public site. Typically, these steps should be automated by the workflow defined in /.github/workflows/publish-docs.yml, which helps ensure that gh-pages isn't being updated with changes that haven't yet been merged into main; however, in some cases, it may be necessary to update gh-pages manually.