Metadata-Version: 2.1
Name: indoc
Version: 0.0.2
Summary: Literal Enum
Home-page: https://github.com/dsm-72/indoc
Author: dsm-72
Author-email: sumner.magruder@yale.edu
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev

# indoc

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Developer Guide

### Setup

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

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

### Install

``` sh
pip install -e .

# install from pypi
pip install indoc
```

### nbdev

``` sh
# 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

``` sh
# 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](https://github.com/dsm-72/indoc):

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

or from [conda](https://anaconda.org/dsm-72/indoc)

``` sh
$ conda install -c dsm-72 indoc
```

or from [pypi](https://pypi.org/project/indoc/)

``` sh
$ pip install indoc
```

## Documentation

Documentation can be found hosted on GitHub
[repository](https://github.com/dsm-72/indoc)
[pages](https://dsm-72.github.io/indoc/). Additionally you can find
package manager specific guidelines on
[conda](https://anaconda.org/dsm-72/indoc) and
[pypi](https://pypi.org/project/indoc/) respectively.

### [`indoc`](https://dsm-72.github.io/indoc/indoc.html#indoc) decorator

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

``` python
@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

``` python
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
```
