diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 3756165..be561bf 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -25,7 +25,7 @@ jobs: # Build the book - name: Build the book run: | - jupyter-book build . + sphinx-build . ./_build/html -b html # Push the book's HTML to github-pages - name: GitHub Pages action @@ -33,4 +33,3 @@ jobs: with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./_build/html - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab64e8d..71a65ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,12 +8,22 @@ You will need to install the requirements: python -m pip install -r requirements.txt ``` -To build the book as HTML execute the following command: +You could build the book as HTML using `jupyter-book`: ```sh python -m jupyter book build . ``` +However because we need OG metadata, the book is built using `sphinx` directly: + +```sh +sphinx-build . ./_build/html -b html +``` + +This is in fact what the GitHub workflow does. + +> The `conf.py` was generated by running `jupyter-book config sphinx .` and adding the `sphinxext.opengraph` extension. + To build the book as PDF install the `pyppeteer` package and execute the build command: ```sh diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..22f68ac --- /dev/null +++ b/conf.py @@ -0,0 +1,39 @@ +############################################################################### +# Auto-generated by `jupyter-book config` +# If you wish to continue using _config.yml, make edits to that file and +# re-generate this one. +############################################################################### +author = 'Mikhail Berkov' +comments_config = {'hypothesis': False, 'utterances': False} +copyright = '2023-' +exclude_patterns = ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build', 'venv'] +extensions = ['sphinx_togglebutton', 'sphinx_copybutton', 'myst_nb', 'jupyter_book', 'sphinx_thebe', 'sphinx_comments', 'sphinx_external_toc', 'sphinx.ext.intersphinx', 'sphinx_design', 'sphinx_book_theme', 'IPython.sphinxext.ipython_console_highlighting', 'sphinx_jupyterbook_latex', 'sphinx_multitoc_numbering', 'sphinxext.opengraph'] +external_toc_exclude_missing = False +external_toc_path = '_toc.yml' +html_baseurl = '' +html_css_files = ['styles.css'] +html_favicon = '' +html_logo = '' +html_sourcelink_suffix = '' +html_static_path = ['_static'] +html_theme = 'sphinx_book_theme' +html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': '', 'jupyterhub_url': '', 'thebe': False, 'colab_url': ''}, 'path_to_docs': '', 'repository_url': 'https://github.com/uhasker/the-python-minibook', 'repository_branch': 'main', 'extra_footer': '', 'home_page_in_toc': True, 'announcement': '', 'analytics': {'google_analytics_id': ''}, 'use_repository_button': True, 'use_edit_page_button': False, 'use_issues_button': True} +html_title = 'The Python Minibook' +latex_engine = 'pdflatex' +myst_enable_extensions = ['colon_fence', 'dollarmath', 'linkify', 'substitution', 'tasklist'] +myst_url_schemes = ['mailto', 'http', 'https'] +nb_execution_allow_errors = True +nb_execution_cache_path = '' +nb_execution_excludepatterns = [] +nb_execution_in_temp = False +nb_execution_mode = 'force' +nb_execution_timeout = 30 +nb_output_stderr = 'show' +numfig = True +pygments_style = 'sphinx' +suppress_warnings = ['myst.domains'] +use_jupyterbook_latex = True +use_multitoc_numbering = True + +# Open Graph metadata +ogp_site_url = "https://uhasker.github.io/the-python-minibook" diff --git a/requirements.txt b/requirements.txt index a1b8a76..1c53cf4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,6 @@ -jupyter-book==0.15 +jupyter-book==1.0.0 +sphinx==7.2.6 +sphinxext-opengraph==0.9.1 matplotlib numpy pygame