keras-team / keras-autodoc

Documentation autogeneration utilities.
Apache License 2.0
30 stars 22 forks source link

keras-autodoc

Autodoc for mkdocs.

keras-autodoc will fetch the docstrings from the functions you wish to document and will insert them in the markdown files.

Take a look at the documentation!

Install

pip install keras-autodoc

We recommend pinning the version (eg: pip install keras-autodoc==0.3.2). We may break compatibility without any warning.

Example

Let's suppose that you have a docs directory:

./docs
|-- autogen.py
|-- mkdocs.yml

The API is quite simple:

# content of docs/autogen.py

from keras_autodoc import DocumentationGenerator

pages = {'layers/core.md': ['keras.layers.Dense', 'keras.layers.Flatten'],
         'callbacks.md': ['keras.callbacks.TensorBoard']}

doc_generator = DocumentationGenerator(pages)
doc_generator.generate('./sources')
# content of docs/mkdocs.yml

site_name: My_site
docs_dir: sources
site_description: 'My pretty site.'

nav:
    - Core: layers/core.md
    - Callbacks:
      - Some callbacks: callbacks.md

Then you just have to run:

python autogen.py
mkdocs serve

and you'll be able to see your website at localhost:8000/callbacks.

Docstring format:

The docstrings used should use the The docstrings follow the Google Python Style Guide with markdown, or just plain markdown.

For example, let's take this class:

class ImageDataGenerator:
    """Generate batches of tensor image data with real-time data augmentation.

    The data will be looped over (in batches).

    # Arguments
        featurewise_center: Boolean.
            Set input mean to 0 over the dataset, feature-wise.
        zca_whitening: Boolean. Apply ZCA whitening.
        width_shift_range: Float, 1-D array-like or int
            - float: fraction of total width, if < 1, or pixels if >= 1.
            - 1-D array-like: random elements from the array.
            - int: integer number of pixels from interval
                `(-width_shift_range, +width_shift_range)`
            - With `width_shift_range=2` possible values
                are integers `[-1, 0, +1]`,
                same as with `width_shift_range=[-1, 0, +1]`,
                while with `width_shift_range=1.0` possible values are floats
                in the interval `[-1.0, +1.0)`.

    # Examples

    Example of using `.flow(x, y)`:
    ```python
    datagen = ImageDataGenerator(
        featurewise_center=True,
        zca_whitening=True,
        width_shift_range=0.2)
    # compute quantities required for featurewise normalization
    # (std, mean, and principal components if ZCA whitening is applied)
    datagen.fit(x_train)
    # fits the model on batches with real-time data augmentation:
    model.fit_generator(datagen.flow(x_train, y_train, batch_size=32),
                        steps_per_epoch=len(x_train) / 32, epochs=epochs)
"""

def __init__(self,featurewise_center, zca_whitening, width_shift_range):
    pass

will be rendered as:

### ImageDataGenerator class:

```python
dummy_module.ImageDataGenerator(featurewise_center, zca_whitening, width_shift_range=0.0)

Generate batches of tensor image data with real-time data augmentation.

The data will be looped over (in batches).

Arguments

Examples

Example of using .flow(x, y):

datagen = ImageDataGenerator(
    featurewise_center=True,
    zca_whitening=True,
    width_shift_range=0.2)
# compute quantities required for featurewise normalization
# (std, mean, and principal components if ZCA whitening is applied)
datagen.fit(x_train)
# fits the model on batches with real-time data augmentation:
model.fit_generator(datagen.flow(x_train, y_train, batch_size=32),
                    steps_per_epoch=len(x_train) / 32, epochs=epochs)

Take a look at our docs

If you want examples, you can take a look at the docs directory of autokeras as well as the generated docs.

You can also look at the docs directory of keras-tuner.