Jupyter-book: Build a Standalone Page: "Path to book isn't a directory"

[CodeCox]

I'm trying to Build a Standalone Page using a simple markdown file.
(I'm keenly exploring jupyter-book for the first time so apologies if I'm off on a tangent. btw nice work!)

Steps to reproduce the behavior:

1. create folder viz. singlepage
2. create _config.yml
3. create onepage.md
4. generate _toc.yml (is this required for a single page? but same error even if omitted.)
5. run build command
   jb build singlepage/onepage.md

Expected behavior
As per doc - "This will execute your content and output the proper HTML in a _build/html folder."

Error

Traceback (most recent call last):
  File "/home/spikex/miniconda3/envs/jubo/bin/jb", line 8, in <module>
    sys.exit(main())
  File "/home/spikex/miniconda3/envs/jubo/lib/python3.7/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/home/spikex/miniconda3/envs/jubo/lib/python3.7/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/home/spikex/miniconda3/envs/jubo/lib/python3.7/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/spikex/miniconda3/envs/jubo/lib/python3.7/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/spikex/miniconda3/envs/jubo/lib/python3.7/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/home/spikex/miniconda3/envs/jubo/lib/python3.7/site-packages/jupyter_book/commands/__init__.py", line 59, in build
    _error(f"Path to book isn't a directory: {PATH_BOOK}")
  File "/home/spikex/miniconda3/envs/jubo/lib/python3.7/site-packages/jupyter_book/utils.py", line 65, in _error
    raise kind(box)
ValueError:
===============================================================================

Path to book isn't a directory: /home/spikex/devx/jubod/singlepage/onepage.md

===============================================================================

Environment

• Python 3.7.8
• Package versions:
  Jupyter Book: 0.7.4
  MyST-NB: 0.9.1
  Sphinx Book Theme: 0.0.36
  MyST-Parser: 0.12.2
  Jupyter-Cache: 0.4.0
• Operating System
  WSL2 (Ubuntu20.04) on Windows10
• miniconda3 env

Additional context
My minimal folder tree:

• singlepage
  
  
  
  • _config.yml
  
  
  • _toc_yml
  
  
  • onepage.md
  
  

Building a book works as expected (using the same steps listed above) ie.
jb build singlepage/

Therefore I have not attached my trivial test content and meta files - they are unlikely to be the source of the problem?

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! :tada:

[AakashGfude]

Hey @CodeCox, Thanks for reporting this and testing jb out. In fact, this was an issue, which we fixed yesterday itself.
We will release a new version of jupyter-book shortly with this bug fix. Meanwhile, if you are keen, you can work with the latest master branch for the fix.

[CodeCox]

Thanks @AakashGfude - 'shorlty' doesn't sound too long so I'll wait for the new version - it's not a showstopper for me so I'll continue exploring and learning until then.

[AakashGfude]

Sure @CodeCox, sounds good.

[AakashGfude]

Hi @CodeCox, also for the version you have in your system, we have a specific command for building single pages called page. Try doing jb page singlepage/onepage.md and let us know if that works for you.

[CodeCox]

Yes @AakashGfude, page does work for jb-v0.7.4

I noticed the new version ie. jb-v0.7.5 (2020-08-26) has since been released. I just upgraded - and page is the cmd that works in this latest incarnation.

Is page or build the cmd that should be used going forward? Is the doc correct(build) or does it need to be updated(page)?

(Also, perhaps the doc's should have a associated version label? This probably should be raised as another issue?)

[chrisjsewell]

perhaps the doc's should have a associated version label?

Yeh, as I was discussing with @AakashGfude, hopefully at some point we will finalise with the readthedocs guys allowing for jupyter-book builds, then there you can have multiple version of the documentation available.
As is, we only show the latest version from the master branch.
I guess another temporary "solution" would be to maintain a seperate branch, from which the documentation is built, and only push to that when releasing new versions

[chrisjsewell]

I just upgraded - and page is the cmd that works in this latest incarnation.

Yes, page will be removed in v0.8.0, and merged with build (soonish)

[CodeCox]

Ok - no worries - now the 'discrepancy' makes more sense to me.

P.S.
I appreciate the situational difficulty. But having the documentation way ahead of the code releases may be problematic/confusing for newcomers _(like me who religiously try to follow any available guidance)_, especially since it is early days and there will be lots of change before things stabilise. In this case, maybe at least about 5 releases _(5? weeks assuming an aggressive weekly release schedule)_ before the code catches up with the current documentation _(which would, of course, no longer be current because master would have moved on by then!)_.

I'd rather have the official web-published documentation always match the latest official release. Advanced users can always look in master for any newer cutting edge stuff.

[AakashGfude]

I'd rather have the official web-published documentation always match the latest official release. Advanced users can always look in master for any newer cutting edge stuff.

True @CodeCox , One of the main motivations for updating docs with the latest master at this stage was to instantly correct any typos or bugs in the documentation for the benefit of the user, but it seems for major releases like the one we are discussing about here, it will do more harm than good. Thanks for your valuable input, much appreciated.

I guess another temporary "solution" would be to maintain a separate branch, from which the documentation is built, and only push to that when releasing new versions.

@chrisjsewell sounds like a nice temporary solution. Something like creating PRs to a develop branch for features, which gets merged to master, only during releases. For pure documentation, directly creating PRs to the master branch. Though might be a bit confusing for external people who are keen on creating PRs, and if we are moving to RTD pretty soon, then probably not worth the effort?

[chrisjsewell]

This should be closed in v0.8.0 😄, but feel free to re-open/open another issue if anything is outstanding: https://jupyterbook.org/reference/_changelog.html#v0-8-0-2020-09-01