indoc

Developer Guide

Setup

# create conda environment
$ mamba env create -f env.yml

# update conda environment
$ mamba env update -n indoc --file env.yml

Install

pip install -e .

# install from pypi
pip install indoc

nbdev

# activate conda environment
$ conda activate indoc

# make sure the indoc package is installed in development mode
$ pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to the indoc package
$ nbdev_prepare

Publishing

# publish to pypi
$ nbdev_pypi

# publish to conda
$ nbdev_conda --build_args '-c conda-forge'
$ nbdev_conda --mambabuild --build_args '-c conda-forge -c dsm-72'

Usage

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/dsm-72/indoc.git

or from conda

$ conda install -c dsm-72 indoc

or from pypi

$ pip install indoc

Documentation

Documentation can be found hosted on GitHub repository pages. Additionally you can find package manager specific guidelines on conda and pypi respectively.

indoc decorator

define (base / mixin) class with a docstring we want to pass to a subclass

@dataclass
class Mix:
    r'''
    A Mixin class

    Attributes
    ----------
    a : str
        a string
    i : int, optional
        an int
    b : bool, optional
        a bool

    Methods
    -------
    is_b(self) -> bool
        checks if b is True    
    '''
    a: str
    _: KW_ONLY
    i: int = 0
    b: bool = False

    @property
    def prop(self):
        return self.a

    @abstractmethod
    def is_b(self) -> bool:
        return self.b

A subclass we want to have Mix’s docstring

foodoc = '''
    A Foo class
    
    Attributes
    ----------
    q : bool

    Methods
    -------
    is_q(self) -> bool
        checks if q is True
    '''    

@indoc
@dataclass
class Foo(Mix):
    __doc__ = foodoc
    q: bool
    def is_q(self) -> bool:
        return self.q