Developer Documentation
My personal docs for things to do for this project. Currently not accepting contributions for this personal project.
Packaging
Run all packaging and development commands from the repository’s root folder.
Versioning
This repository follows Semantic Versioning 2.0.0. When creating new releases, ensure that the version number is updated in the following places
meta.yaml
: For conda buildssrc/featmf/__about__.py
: For the python packagedocs/conf.py
: For the documentation
The package dependencies have to be updated in the following places
setup_conda.sh
: For developers using condameta.yaml
: For conda buildsdocs/requirements.txt
: For building the docs (sphinx).
PyPI
Install the required packages for building the wheels. You need to do this only once.
conda install -c conda-forge hatch twine
Ensure that the pyproject.toml
file is up to date. Build and install the project using
# Manual build
python -m build
# Build using hatch
hatch build
# Install (and uninstall) the wheel directly
pip install ./dist/featmf-0.1.0-py3-none-any.whl
pip uninstall featmf
Upload the package to PyPI using
# Upload to PyPI
python -m twine upload --verbose ./dist/*
Conda
Install the required build tools. You need to do this only once.
conda install conda-build anaconda-client
When developing, it’s better to not build, but just add folder to path. This way, modifications you make are reflected (live) without re-building package. You can manage the developer install (add to path and test the package) using
# Install (add the folder to conda.pth)
conda develop ./src
# Verify if this worked (path should be present)
cat $CONDA_PREFIX/lib/python3.9/site-packages/conda.pth
# Remove this (after testing is over)
conda develop -u ./src
Build and install the package (locally) using
# Set channels (arguments to the build call)
chlist="-c conda-forge -c pytorch -c nvidia ..."
# Build (default output in: ~/anaconda3/conda-bld)
conda build . $chlist
# See the path (verify the file)
conda build --output . $chlist
# Install
conda install --use-local featmf
# Clear builds (if you want to rebuild later)
conda build purge
Once the package is build, upload the package to Anaconda (personal user avneesh-mishra)
# Login (if not done already)
anaconda login -h
anaconda login --hostname HOSTNAME --username ANACONDA_USERNAME \
--password ANACONDA_PASSWORD
# Upload the tar ball as a package (see --output of build for path)
anaconda upload $HOME/anaconda3/conda-bld/linux-64/featmf-0.1.0-py39_0.tar.bz2
# Verify the package by local install
conda install -c avneesh-mishra featmf
Sphinx
The following dependencies were used to create the docs (one time install)
conda install -c conda-forge sphinx sphinx-rtd-theme sphinx-copybutton
pip install sphinx-reload
sphinx-quickstart docs
The above commands were installed using conda
, but the requirements.txt
(in the docs
folder) is populated using pip
like entries in parallel.
If you get an error saying that a package was not found, populate it with an appropriate entry and try again. This is to install only sphinx packages in the build pipeline for the docs (don’t add everything here).
Build the docs using
# Traditional
cd docs
make html
# Live reload
sphinx-reload docs
References
- Sphinx
Directives for markups
- Code Documentation
Autodoc code Documentation: Main extension
- Domains for referencing
Info fields for declaring the type of function parameters and variables
Describing code in Sphinx tutorial
- Packaging
- Conda
- conda-build: Building packages
- Anaconda.org User Guide: Getting started