feat: build the book with Sphinx and add OG metadata

.github/workflows/publish.yml

@@ -25,12 +25,11 @@ 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
         uses: peaceiris/actions-gh-pages@v3.6.1
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./_build/html
-

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

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"

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