Repo organization for book with local package

[cranmer]

Say I have a book that pairs with a local package and the notebooks need to import the package.
Eg. say I want to make a Jupyter book around this repository https://github.com/ctgk/PRML
It's not super obvious how to handle the requirements.txt and setup.py in that case and where they should go.
Should it be organized like this with the package parallel to the book:

repo
 - book/
    - _toc.yml
    - _config.yml
    - notebook.ipynb
    - requirements.txt
 - package
    - __init__.py

or like this with the package inside the book

repo
 - book/
    - _toc.yml
    - _config.yml
    - notebook.ipynb
    - requirements.txt
    - package
       - __init__.py

And suggestions on the requirements / setup / postBuild for building the book with GitHub actions and working with Binder?

[matthewfeickert]

Seems like the first example (with the package and the book being at the same top level) makes more sense conceptually to me. I say this based on the view that for a library you could conceptually view the book/ similar to the docs/ (as jupyter-book itself seems to do). So for a toy example this might look something like

$ tree
.
├── book
│   ├── _config.yml
│   ├── notebook.ipynb
│   ├── requirements.txt
│   └── _toc.yml
├── setup.cfg
├── setup.py
└── src
    └── package
        └── __init__.py

3 directories, 6 files

suggestions on the requirements / setup / postBuild for building the book with GitHub actions and working with Binder

Seems like you could just install the package locally, then install requirements for the book, then build the book

python -m pip install .
python -m pip install -r book/requirements.txt
jupyter-book build book/

[cranmer]

It worked, thanks @matthewfeickert

Book:
https://cranmer.github.io/stats-ds-book/prml_notebooks/attribution.html

Repo:
https://github.com/cranmer/stats-ds-book

Modified deploy script:
https://github.com/cranmer/stats-ds-book/blob/master/.github/workflows/deploy-jupyter-book.yml#L23

[matthewfeickert]

@cranmer Ah, I should have asked more about what your end goal was. Unless you need to make cusotm modification to it, it is probably better to just install prml from GitHub than vendor it yourself. Example:

$ cat requirements.txt 
git+https://github.com/ctgk/PRML.git
$ python -m pip install -r requirements.txt 
Collecting git+https://github.com/ctgk/PRML.git (from -r requirements.txt (line 1))
  Cloning https://github.com/ctgk/PRML.git to /tmp/pip-req-build-76pu4a8q
Collecting numpy
  Using cached numpy-1.19.1-cp37-cp37m-manylinux2010_x86_64.whl (14.5 MB)
Collecting scipy
  Using cached scipy-1.5.2-cp37-cp37m-manylinux1_x86_64.whl (25.9 MB)
Building wheels for collected packages: prml
  Building wheel for prml (setup.py) ... done
  Created wheel for prml: filename=prml-0.0.1-py3-none-any.whl size=87144 sha256=a0a3fca43a0355e8ab851a9d668db18cb85727d51e4b37c2e017a9d74ad3e4f6
  Stored in directory: /tmp/pip-ephem-wheel-cache-9b71xazp/wheels/4d/3b/c2/0d60c9de5cf31ae73ed9c46be32f890ca4d590c3655087a1cf
Successfully built prml
Installing collected packages: numpy, scipy, prml
Successfully installed numpy-1.19.1 prml-0.0.1 scipy-1.5.2
$ pip list | grep prml
prml          0.0.1

then the only thing you would need to vendor is the notebooks from prml, but you don't have to also maintain/vendor the code.

[cranmer]

yes, good point. I have a different example where I'm providing the code, so I needed to work through it either way.