executablebooks / cookiecutter-jupyter-book Goto Github PK

In contributing.md link to the jupyter-book contributing docs and generally improve the contributing docs and development guidelines.

Minor suggestions, currently the book URL and user check is hardcoded to GitHub. Maybe there could be a choice in the beginning about which version control host to use (like with the end for the CI now). Then the rest of the options could be generic ("username", "ci", etc) and the host URL would be prefaced where needed.

Changing the url to gitlab also gives this warning so maybe binder should be turn off if gitlab is chosen (with a messge): WARNING: Currently Binder/JupyterHub repositories must be on GitHub, got https://gitlab.com/

Describe the problem

I am trying to build a jupyter book and everything is alright until I try to build the HTML render using jupyter-book build my-book/. Then I get an error message saying ImportError: DLL load failed while importing win32api: The specified module could not be found.

From what I can tell win32api changed its name to pywin32. I installed that and even tried installing win32api but it says it can't be found (probably because the name changed). I don't know how to make jupyter books not look for win32api and look for pywin32 instead. Or maybe there's another way around the issue I haven't figured out.

Link to your repository or website

https://github.com/RoxaneT/en_Physics_test

Steps to reproduce

I put the folder with all the files from the book in the repo I linked. I followed the instructions in your readme, so if you clone that and try to build it from there you might get the same error.

The version of Python you're using

3.8

Your operating system

Windows 10 Pro

Versions of your packages

Jupyter Book      : 0.11.2
External ToC      : 0.2.3
MyST-Parser       : 0.13.7
MyST-NB           : 0.12.3
Sphinx Book Theme : 0.1.2
Jupyter-Cache     : 0.4.3
NbClient          : 0.5.4

Additional context

No response

Update the cookiecutter as required when this PR is ready: executablebooks/jupyter-book#1293

I've been focussing on managing/improving code in the cookiecutter template, but #31 was a good reminder that I need to revisit and revise the documentation files (README, CONDUCT, etc.) to make sure they are still current and relevant.

Context

The current cookiecutter mostly presents code options for the license, rather than more conventional document licenses. Primarily, the various creative commons licenses!

Proposal

Add a couple of common CC licenses - at least CC BY and CC BY-SA. Perhaps at the cost of removing some of the existing licenses (I'd suggest GPL (which is equivalent IMO to CC BY-SA), and perhaps ISC)

Tasks and updates

No response

Describe the problem

The image at linked to in {{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/notebooks.ipynb (https://myst-parser.readthedocs.io/en/latest/_static/logo.png) no longer exists:

A new image should be linked to there.

Link to your repository or website

No response

Steps to reproduce

It exists locally, and in the example on the web (https://executablebooks.github.io/cookiecutter-jupyter-book/notebooks.html).

The version of Python you're using

No response

Your operating system

No response

Versions of your packages

No response

Additional context

No response

Describe the bug

I tried to use the cookie cutter command, but there was a key error when Jupyter Book tried to write the files.

To Reproduce

$ jupyter-book create docs/ --cookiecutter
You've downloaded /home/hankdoupe/.cookiecutters/cookiecutter-jupyter-book before. Is it okay to delete and re-download it? [yes]: yes
author_name [Captain Jupyter]: Hank Doupe	
github_username [hankdoupe]: hdoupe
book_name [my-book]: docs
book_slug [docs]: docs
book_short_description [This cookiecutter creates a simple boilerplate for a Jupyter Book.]: Developer documentation for Compute Studio.
version ['0.1.0']: 
Select open_source_license:
1 - MIT license
2 - BSD license
3 - ISC license
4 - Apache Software License 2.0
5 - GNU General Public License v3
Choose from 1, 2, 3, 4, 5 [1]: 5
Select include_ci:
1 - github
2 - gitlab
3 - no
Choose from 1, 2, 3 [1]: 1
Traceback (most recent call last):
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/cookiecutter/generate.py", line 352, in generate_files
    generate_file(
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/cookiecutter/generate.py", line 175, in generate_file
    rendered_file = tmpl.render(**context)
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/jinja2/environment.py", line 1090, in render
    self.environment.handle_exception()
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/jinja2/environment.py", line 832, in handle_exception
    reraise(*rewrite_traceback_stack(source=source))
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/jinja2/_compat.py", line 28, in reraise
    raise value.with_traceback(tb)
  File "./LICENSE", line 82, in top-level template code
jinja2.exceptions.UndefinedError: 'collections.OrderedDict object' has no attribute 'project_short_description'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/hankdoupe/miniconda3/bin/jupyter-book", line 8, in <module>
    sys.exit(main())
  File "/home/hankdoupe/.local/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/home/hankdoupe/.local/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/home/hankdoupe/.local/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/hankdoupe/.local/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/hankdoupe/.local/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/jupyter_book/commands/__init__.py", line 286, in create
    book = cookiecutter(cc_url, output_dir=Path(path_book))
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/cookiecutter/main.py", line 101, in cookiecutter
    result = generate_files(
  File "/home/hankdoupe/miniconda3/lib/python3.8/site-packages/cookiecutter/generate.py", line 359, in generate_files
    raise UndefinedVariableInTemplate(msg, err, context)
cookiecutter.exceptions.UndefinedVariableInTemplate: Unable to create file 'LICENSE'. Error message: 'collections.OrderedDict object' has no attribute 'project_short_description'. Context: OrderedDict([('cookiecutter', OrderedDict([('author_name', 'Hank Doupe'), ('github_username', 'hdoupe'), ('book_name', 'docs'), ('book_slug', 'docs'), ('book_short_description', 'Developer documentation for Compute Studio.'), ('version', "'0.1.0'"), ('open_source_license', 'GNU General Public License v3'), ('include_ci', 'github'), ('_template', 'gh:executablebooks/cookiecutter-jupyter-book')]))])

Expected behavior

No errors.

$ jupyter-book build mybook
ERROR ...

Environment

$ jupyter-book --version
Jupyter Book: 0.8.2
MyST-NB: 0.10.1
Sphinx Book Theme: 0.0.37
MyST-Parser: 0.12.10
Jupyter-Cache: 0.4.1
NbClient: 0.5.0
(base) ~/compute-studio 
$ python --version
Python 3.8.1
(base) ~/compute-studio 

OS: Ubuntu

Thanks for taking a look at this! I'm just getting started with Jupyterbooks and the cookie cutter command seemed like the right way to template everything out!

Wondering if including a Makefile might be a good idea? To me this is very helpful in onboarding to repositories as I can look to see what the commands are, and my previous relationships with sphinx always had Makefiles I believe?!

Even if they are small wrappers on the jupyter-book CLI make build/html/docs/serve

It was pointed out that not all users will have GitHub usernames, or may make mistakes when entering their username. As this username is used to populate cookiecutter files, we should check that the name is valid, and raise a warning if not.

I'm thinking that this could be done with requests:

import requests

if not requests.get("http://www.github.com/tomasbeuzen").status_code < 400:
    # raise a warning

This adds ~ 2 seconds onto the post generation workflow, I'll try it out and see how it goes...

As per the announcement that GitHub is phasing out the master terminology for main, I need to:

1. Update this repo's branch to main
2. Update the CC files to reference "main"

Jupyter Book is under active development, I should:

• Create a simple GH action to try and build the CC
• Create an action to auto-deploy the example book

Context

The documentation of the actions-gh-pages workflow now links to the official GitHub Actions deploy-pages workflow:

Note

See also the GitHub official GitHub Pages Action first.

• GitHub Pages now uses Actions by default | The GitHub Blog
• GitHub Pages: Custom GitHub Actions Workflows (beta) | GitHub Changelog

Could this be used instead?

Proposal

Replace actions-gh-pages with deploy-pages.

Tasks and updates

• check if deploy-pages would allow for publishing the jupyter-book site
• update the cookiecutter-jupyter-book/.github/workflows/deploy.yml file

I need to improve the testing regime for the CC, ideally I'd like to add the following:

1. Include the same test currently being run in Jupyter Book (we don't want that to break!)
2. Run CC for all possible combinations of options. There are currently 6 "license options" and 3 "include_ci" options. So that's only 18 combinations and the tests are very quick to run so this should be fine.

#7 raised the issue of supporting GitLab with the inclusion of a .gitlab-ci.yml file.

This issue touches on the larger issue of making the cookiecutter more hoster agnostic (right now it is very GitHubby). A few things to fix:

• Only add the book url if github is selected as the hosting platform: this line
• Change the user-checking functionality: this line
• Create tests for other supported platforms like GitLab (this will probably be another issue)

Update with more thoughts:

• I want to keep the CC as simple but functional as possible
• At this point, I can only imagine GitHub and GitLab being used as hosting platforms, so let's stick with accommodating those for now
• Ideally, the CC would ask a user if they were going to host on GitHub or GitLab, and then customize the following things it asks based on that response, but unfortunately this conditional format is still under dev in CC (no idea when it will be implemented, if ever)

Want to host books using on-premise gitlab installation. For that, need to have a properly configured .gitlab-ci.yml file.
This will be a translation of https://github.com/executablebooks/cookiecutter-jupyter-book/blob/master/%7B%7Bcookiecutter.book_slug%7D%7D/.github/workflows/deploy.yml

Here is an example of such file for jupyter-book: https://hackmd.io/@mechatronics3d/S1lfojdjL

Describe the bug

The readme file's build instructions say

(Recommended) Remove the existing {{ cookiecutter.book_name }}/_build/ directory
Run jupyter-book build {{ cookiecutter.book_name }}/

however the directory is actually named {{cookiecutter.book_slug}}.

To Reproduce

Steps to reproduce the behavior:

Create a book where the book name and slug are different and follow the build instructions in the generated readme

Expected behavior

A clear and concise description of what you expected to happen.

Readme should read

(Recommended) Remove the existing {{ cookiecutter.book_slug }}/_build/ directory
Run jupyter-book build {{ cookiecutter.book_slug }}/

Environment

• Python Version [e.g. 3.7.1]: 3.8.6
• Package versions or output of jupyter-book --version:

Jupyter Book: 0.10.1
MyST-NB: 0.12.0
Sphinx Book Theme: 0.0.41
MyST-Parser: 0.13.5
Jupyter-Cache: 0.4.2
NbClient: 0.5.2

• Operating System: WSL

Additional context

Add any other context about the problem here.