Workflow¶
This page describes the tooling used during development of this project. It also serves as a reference for the various commands that you would use when working on this project.
Overview¶
This project uses the GitHub Flow for collaboration. The codebase contains Python code, Jinja2-based HTML pages, Sass stylesheets and Javascript code.
- nox is used for automating development tasks. 
- Gulp-based build pipeline is used to process the Sass and Javascript files. 
- sphinx-autobuild is used to provide live-reloading pages when working on the theme. 
- pre-commit is used for running the linters. 
Initial Setup¶
To work on this project, you need to have git 2.17+, Python 3.6+ and NodeJS 12.
- Clone this project using git: - git clone https://github.com/pradyunsg/furo.git cd furo 
- Install the project’s dependencies: - npm install pip install nox 
You’re all set for working on this project.
Commands¶
Local Development Server¶
nox -s docs-live
Serve this project’s documentation locally, using sphinx-autobuild. This will open the generated documentation page in your browser.
The server also watches for changes made to the documentation (docs/) or theme (src/), which will trigger a rebuild. Once the build is completed, server will automagically reload any open pages using livereload.
Tip
My workflow, when I’m working on this theme, is along the lines of:
- Run this command, and wait for the browser window to open. 
- alt+tab gets me back to my text editor. 
- Make changes to some files and save those changes. 
- alt+tab switches to the browser. 
- After a small delay, the change is reflected in the browser. 
- If I want to make more changes, alt+tab and I’m back to my text editor. 
- Repeat the previous 4 steps until happy. 
- @pradyunsg
Documentation Generation¶
nox -s docs
Generate the documentation for Furo into the build/docs folder. This (mostly) does the same thing as nox -s docs-live, except it invokes sphinx-build instead of sphinx-autobuild.
Release process¶
- Update the changelog 
- Run - nox -s release
- Once that command succeeds, you’re done!