Support non-library projects

[Isaac-Flath]

cc: @jph00

The fastai/apl-study repo no longer builds the website due do nbdev_docs failing. I looked into it, and have am easy workaround. I think it'd be better to fix in the main library, if this is a desired use case for nbdev. I'd love to work on the PR, but wanted to document the issue and get OK on direction first.

The Explanation

nbdev_docs now requires a _modidx.py file. For anything that isn't a python library that does not exist. When nbdev_docs is called, it attempts to create the modidx.py file via nbdev.doclinks._build_modidx. This fails because the lib_path directory defined in the settings.ini does not exist because it's not a library so it was never created. If you create that directory as an empty directory with mkdir the docs build correctly.

Question

The first question is: Is this use case is something nbdev should support, or if applications where there is no python library would be better suited for Quarto in the future?

Possible Solutions

I am happy to submit a PR for either of these solutions below, or another approach if you have other ideas.

The fastest workaround would be to have a workaround would be for _build_modidx to create lib_path if it does not exist. I think a better solution would be to modify the process so that a _modidx is not required if there is no library as part of the nbdev project.

Details

Recreate the issue

• Clone the apl-study repo
• run nbdev_docs

(base) ✔ ~/github/fastai/apl-study [master|✔] 
20:21 $ nbdev_docs
NB: From v1.2 `_quarto.yml` is no longer auto-updated. Please remove the `custom_quarto_yml` line from `settings.ini`
Traceback (most recent call last):
  File "/Users/isaacflath/opt/miniconda3/bin/nbdev_docs", line 8, in <module>
    sys.exit(nbdev_docs())
  File "/Users/isaacflath/opt/miniconda3/lib/python3.9/site-packages/fastcore/script.py", line 119, in _f
    return tfunc(**merge(args, args_from_prog(func, xtra)))
  File "/Users/isaacflath/opt/miniconda3/lib/python3.9/site-packages/nbdev/quarto.py", line 227, in nbdev_docs
    cache,cfg,path = _pre_docs(path, n_workers=n_workers, **kwargs)
  File "/Users/isaacflath/opt/miniconda3/lib/python3.9/site-packages/nbdev/quarto.py", line 173, in _pre_docs
    nbdev.doclinks._build_modidx()
  File "/Users/isaacflath/opt/miniconda3/lib/python3.9/site-packages/nbdev/doclinks.py", line 98, in _build_modidx
    idxfile.write_text("# Autogenerated by nbdev\n\nd = "+pformat(res, width=140, indent=2, compact=True))
  File "/Users/isaacflath/opt/miniconda3/lib/python3.9/pathlib.py", line 1285, in write_text
    with self.open(mode='w', encoding=encoding, errors=errors) as f:
  File "/Users/isaacflath/opt/miniconda3/lib/python3.9/pathlib.py", line 1252, in open
    return io.open(self, mode, buffering, encoding, errors, newline,
  File "/Users/isaacflath/opt/miniconda3/lib/python3.9/pathlib.py", line 1120, in _opener
    return self._accessor.open(self, flags, mode)
FileNotFoundError: [Errno 2] No such file or directory: '/Users/isaacflath/github/fastai/apl-study/apl-study/_modidx.py'

Workaround

• run mkdir apl-study
• run nbdev_docs

(base) ✘-1 ~/github/fastai/apl-study [master|✚ 1…1] 
20:21 $ mkdir apl-study
(base) ✔ ~/github/fastai/apl-study [master|✚ 1…1] 
20:21 $ nbdev_docs 
NB: From v1.2 `_quarto.yml` is no longer auto-updated. Please remove the `custom_quarto_yml` line from `settings.ini`
[1/7] 01_APL.ipynb
[2/7] 02_functions.ipynb
[3/7] 04_competition.ipynb
WARNING: Unable to resolve link target: APL.ipynb
WARNING: Unable to resolve link target: operators.ipynb
[4/7] 05_the_rest.ipynb
[5/7] 03_operators.ipynb
[6/7] python.ipynb
[7/7] index.ipynb

Output created: _docs/index.html

[Isaac-Flath]

Closing this out as I just saw while I was working on this, you fixed the issue in the apl-study repo by adding the _modidx.py file already and upgraded nbdev version. There's another error in workflow, but the issue above cannot be recreated now so closing out. Leaving it to you as you're working on it, but let me know if you'd like any further help.
Thanks!

[jph00]

I'm reopening it because it's better to fix the lib for other non-library projects. The issues I found were:

• The gh action always calls pip install -e . which fails when it's not a lib
• nbdev tries to build _modidx.py but can't

[dleen]

I just ran into this same issue while making a gradual onboarding guide for my users. nbdev_clean, nbdev_fix, and a few others work on non-libraries, but hit a wall on nbdev_docs.

So I would love this feature.

[hamelsmu]

@dleen I would love to take a look at the onboarding guide if possible! I'll try and tackle this soon