menu items are linked to html folders, not the html files/ What to add in repo?

[keunwoochoi]

Hi, thanks for nice project. I'm new to any sort of documentation and wanted to use pydocmd for my python package. I found it a bit confusing to understand the exact workflow for pydocmd. I think it could be easier for beginners if READMD is more like a tutorial with the same sequence that users have to do. I'd like to PR but after I make it to properly use it for myself. Below is what I am understanding now.

Let's say my_proj is the project folder

1. $ cd docs
   $ pydocmd new

   Now I have docs/pydocmd.yml.

2. Edit docs/pydocmd.yml to generate .md files.

   
   site_name: Kapre Documentation
   generate:
   - time_frequency.md:
   - kapre.time_frequency+
   - filterbank.md:
   - kapre.filterbank+
   - utils.md:
   - kapre.utils+
   - augmentation.md:
   - kapre.augmentation+
   - datasets.md:
   - kapre.datasets

pages:

• Home: index.md << ../README.md
• Modules:
  • time_frequency: time_frequency.md
  • filterbank: filterbank.md
  • utils: utils.md
  • augmentation: augmentation.md
  • datasets: datasets.md

theme: readthedocs docs_dir: sources gens_dir: _build/pydocmd # default (-> MkDocs docs_dir) site_dir: _build/site # default loader: pydocmd.loader.PythonLoader # default preprocessor: pydocmd.preprocessor.Preprocessor # default

repo_url: http://github.com/keunwoochoi/kapre site_url: http://kapre.readthedocs.io site_description: 'Documentation for Kapre, Keras Audio Preprocessor layers'

3. 

$ pydocmd generate

This creates many `.md` files under `docs/_build/pydocmd/`.

4. 

$ pydocmd build

This creates whole static html files under `docs/_build/site/`.

Q1.

BUT, when I open the `index.html` there, it seems perfect except the links on the left menus are connected to `file:///Users/gnu/Gnubox/kapre/docs/_build/site/time_frequency/` instead of `file:///Users/gnu/Gnubox/kapre/docs/_build/site/time_frequency/index.html`. What am I doing wrong?

Q2. 
After fixing it, which file should I add and commit so that readthedocs can automatically notice it and update the doc on web?

Thanks a lot!

[NiklasRosenstein]

Thanks for the feedback, I'll update the information to be clearer similar to what you suggested. :)

> Q1: Hm, I think that depends on the theme you are using, or maybe it is a "feature" of MKDocs, since typically a web server like NGinx will server a request to time_frequency/ from time_frequency/index.html. I'll check it out later. Either way, this is an MKDocs issue.

> Q2: I haven't used pydocmd with readthedocs yet. It seems, it only supports Sphinx and MKDocs. Unfortunately, pydocmd has to generate the documentation files first, thus it won't work with readthedocs unless they give you the ability to run some custom commands to build the documentation.

See http://docs.readthedocs.io/en/latest/builds.html

[keunwoochoi]

I see. Really don't know much about web stuff and didn't expect documentation could be such a pain.. anyway, thanks!

[NiklasRosenstein]

I hope it's a bit clearer now :)