occlib is The Open Cinema Collective’s python library template. To build your own
documentation, simply start using it. Below we will show some example documentation with
the basic functions of this library template.
use occlib::cast_spell; assert_eq!(cast_spell(), "Avada Kedavra")
Occlib comes with a number of pre-built quality-of-life macros for developers so they
can code more and manage less, most of which are accessed through
In addition to your lib’s package folder, occlib has two other main directories:
./zdevelop- where maintenance scripts, and other information is stored
In addition, the following files are used:
./README.md- brief description and pointer to doc link for Github
./setup.cfg- when possible, settings for all tools are stored here.
./tarpaulin.toml- configuration for code coverage with tarpaulin.
./Makefile- contains make commands for the development features detailed in this doc.
./azure_pipelines.yml- build process definition for Azure Pipelines.
Getting started is easy, just follow the below steps. Many of these steps include
Make scripts that help you get up and running quickly. To run the
ensure that the active directory of your terminal session is
- Clone occlib-go from Github
navigate to where you wish to keep your project in terminal: ::
cd /path/to/local_repository git clone https://github.com/opencinemac/occlib-rs.git
once the library is cloned, move into it as your active directory:
- Pick a Name
When you have chosen a name for your new lib, update the Cargo.toml.
- Pick a Description
./Cargo.toml file, under the
[metadata] header, change the
field to a brief description of your project.
- Initialize a new git repo
You should delete the existing
.git folder for the repository, then initialize a
clean repo by typing:
In the future, you may wish to cherry-pick commits / updates to this template into your own libraries. A guide for how to do that can be found here:
[Guide needs to be written]
- Register your library
Please reference the relevant documentation for registering your library in Github, Azure Pipelines, etc. Links to relevant guides can be found below:
[Guides need to be written]
The Open Cinema Collective’s style guide is simple and straightforward:
This keeps things simple, but consistent.
To check the formatting of your library, type:
This will run the following tools to tell you where adjustments need to be made:
Strict pep8 and Black adherence, while useful in many ways to the organization, can be annoying and distracting to individual engineers. To help with this, the occlib template comes with tools to re-format your code for you.
To re-format your code, type:
This will run the following tools:
With these tools, keeping your code properly formatted is minimally invasive, and as an organization will lead to a more consistent, maintainable codebase.
To run your tests type:
occlib uses the built-in cargo tools to making documentation. To create docs for your library, type:
- Make Commits:
Make your commits as you work. Your commits will be made to the
dev branch, changes
are pushed to master automatically once builds are passed.
The major / minor version of the library are set in the
setup.cfg file under
Patch versions are generated automatically by the build system. So if
1.2 and the last published build was
1.2.4 the next build created will
When a new major / minor version bump is desired, simply change the
When you are ready, push your code to github. This will set off a chain of events that will:
- automatically run formatting and unit tests
- if tests are passed, build and push your library to be available to other developers
- uploads a new version to crates.io
occlib uses Azure Pipelines to automatically run builds.
For more information on azure builds, see the azure build templates repo.
- Scratch Folder
zdevelop/scratch is included in .gitignore, so you can store scratch work
to do quick tests in this directory without accidentally causing a commit conflict.
casts a spell