keras-team/keras-autodoc

Cannot properly configure autogen.py

ccamara opened this issue · 6 comments

ccamara commented

I am completely new to python and mkdocs, so I started a pet project for testing purposes and I wanted to use keras-autodoc for documenting my own functions (looks really promising, and I can use markdown instead of rst).

If I am not wrong, after configuring autogen.py and running mkdocs serve a new .md file will be created with the documentation of all functions listed within the pages variable.

After reading readme.md file, I tried to adapt it to my project, but without success.
My project uses the following structure:

├── docs/   <- where mkdocs and autogen.py are located.
├── src                <- Source code for use in this project.
│   ├── __init__.py    <- Makes src a Python module
│   ├── features       <- Scripts to turn raw data into features for modeling
│           ├── __init__.py   
│           └── bcn_trees.py

You can see the complete repo here

With that structure, I created a docs/autogen.py file with the following content:

# content of docs/autogen.py

from keras_autodoc import DocumentationGenerator

pages = {
    'api_bcn_trees.md': [
        'bcn_trees.data_download',
        'bcn_trees.data_munging']
    }

doc_generator = DocumentationGenerator(pages)
doc_generator.generate('./sources')

but when running mkdocs serve the api_bcn_trees.md file is not generated. What am I doing wrong?

gabrieldemarmiesse commented

Do you have an error message? If so can you post it too? I believe your problem is just configuring the imports correctly.

ccamara commented

Sure! I get the following warning:

WARNING - A relative path to 'functions_bcn_trees.md' is included in the 'nav' configuration, which is not found in the documentation files

The file is not generated, and yes, I believe you are right, but I have no clue on how to configure imports correctly. Could you please help me with that?

gabrieldemarmiesse commented
ccamara commented

Thanks again!
Apologies again, but since I have just landed to python, I am not yet familiar with importing and installing projects. That's what I've done so far:

  1. create a /setup.py file in my root folder. Since I am not familiar with it, I left the default contents generated by Cookiecutter DataScience:
from setuptools import find_packages, setup

setup(
    name='src',
    packages=find_packages(),
    version='0.1.0',
    description='Scripts for preparing data improrts to OSM.',
    author='Carlos Cámara',
    license='MIT',
)
  1. Run pip install -e ./:
Obtaining file:///home/ccamara/www/osm_imports_preparations
Installing collected packages: src
  Running setup.py develop for src
Successfully installed src
  1. Edit autogen.py with the following content:
# content of docs/autogen.py

from keras_autodoc import DocumentationGenerator

from src.features import bcn_trees



pages = {
    'api_bcn_trees.md': [
        'src.data_download',
        'src.data_munging']
    }

doc_generator = DocumentationGenerator(pages)
doc_generator.generate('./sources')
  1. Run mkdocs serve, but unfortunately, nofunctions_bcn_trees.md file is generated:
$ mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
WARNING -  A relative path to 'functions_bcn_trees.md' is included in the 'nav' configuration, which is not found in the documentation files 
[I 191221 14:07:15 server:296] Serving on http://127.0.0.1:8000
[I 191221 14:07:15 handlers:62] Start watching changes
[I 191221 14:07:15 handlers:64] Start detecting changes
[I 191221 14:07:49 watcher:104] Running task: builder (delay: None)
INFO    -  Building documentation...

What am I missing?

gabrieldemarmiesse commented

in pages, try to change src.data_download by src.features.bcn_trees.data_download.
Also remember to execute the autogen.py before doing mkdocs serve.

ccamara commented

Oh! thank you! After changing the path in pages and making sure to run autogen.py before mkdocs serve (I thought that that command triggered autogen.py, but I was wrong, so thanks for pointing this out), it is working great! Thanks for your great job and for guiding me with this issue! (I have credited you in the repo following the all-contributors guidelines: https://github.com/ccamara/osm_imports_preparations#contributors-)