Quarto Book (#1)

Initialize and configure quarto book project for documentation site.

.github/workflows/quarto-pages.yml

@@ -0,0 +1,86 @@
+
+# https://jupyterbook.org/en/stable/publish/gh-pages.html
+
+name: quarto-pages
+
+on:
+  push:
+    branches:
+    - main
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder has been modified.
+    #
+    #paths:
+    #- docs/**
+
+  # make this workflow manually runnable
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
+  workflow_dispatch:
+
+
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v3
+
+    #
+    # PYTHON STUFF
+    #
+
+    # INSTALL PYTHON
+    #- name: Set up Python 3.11
+    #  uses: actions/setup-python@v4
+    #  with:
+    #    python-version: 3.11
+
+    # INSTALL PACKAGE DEPENDENCIES (IF YOU ARE DOCUMENTING YOUR PACKAGE)
+    #- name: Install dependencies
+    #  run: |
+    #    pip install -r requirements.txt
+
+    # INSTALL DOCUMENTATION DEPENDENCIES
+    #- name: Install docs dependencies
+    #  run: |
+    #    pip install -r docs/requirements.txt
+
+    #
+    # QUARTO STUFF
+    #
+
+    # INSTALL QUARTO
+    # https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml
+    - name: Set up Quarto
+      uses: quarto-dev/quarto-actions/setup@v2
+      #env:
+      #  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        # To install LaTeX to build PDF book
+        # (to get past errors on the CI build)
+        tinytex: true
+        # uncomment below and fill to pin a version
+        # version: SPECIFIC-QUARTO-VERSION-HERE
+
+    # RENDER WEBSITE CONTENTS TO DOCS/_BUILD
+    - name: Build the book
+      run: |
+        quarto render docs/
+
+    #
+    # GITHUB PAGES STUFF
+    #
+
+    # UPLOAD CONTENTS OF DOCS/_BUILD
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: "docs/_build"
+
+    # DEPLOY WEBSITE CONTENTS TO GITHUB PAGES
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v2

Makefile

@@ -0,0 +1,14 @@
+
+
+build:
+	quarto render docs/
+	open docs/_build/index.html
+
+preview:
+	quarto preview docs/
+
+render:
+	quarto render docs/
+
+open:
+	open docs/_build/index.html

docs/.gitignore

@@ -0,0 +1 @@
+/.quarto/

docs/README.md

@@ -0,0 +1,67 @@
+
+# Quarto Docs
+
+## Prerequisites
+
+### Quarto
+
+We need to install Quarto onto your local machine. You can [download](https://quarto.org/docs/get-started/), or [install via homebrew](https://formulae.brew.sh/cask/quarto) (if you like that kind of thing):
+
+```sh
+brew install --cask quarto
+```
+
+If you use VS Code, you can also consider installing the [Quarto Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto).
+
+### Setup
+
+Fork the repo. Clone your copy of the repo onto your computer and navigate to it from the command line.
+
+Setup virtual environment:
+
+```sh
+#conda create -n quarto-env python=3.10
+#conda activate quarto-env
+```
+
+Install package dependencies:
+
+```sh
+#pip install -r requirements.txt
+#pip install -r docs/requirements.txt
+```
+
+## Initialization
+
+FYI the following command was used to initialize the quarto config:
+
+```sh
+#quarto create book
+```
+
+In the docs/_quarto.yml file, the output directory was changed from _book to _build to standardize across projects, enabling the usage of common workflow files and makefile.
+
+## Building
+
+
+Previewing the site (runs like a local webserver):
+
+```sh
+quarto preview docs/
+```
+
+
+Rendering the site (writes local HTML files to the "docs/_build" directory, which is ignored from version control):
+
+```sh
+quarto render docs/ --verbose
+```
+
+
+## GitHub Actions Workflows
+
+### Website Publishing
+
+We are using the ["quarto-pages.yml" workflow configuration file](/.github/workflows/quarto-pages.yml) to deploy the site to GitHub Pages when new commits are pushed to the main branch.
+
+In order for this to work, you first need to configure your GitHub Pages repo settings to publish via GitHub Actions.

docs/_quarto.yml

@@ -0,0 +1,25 @@
+project:
+  type: book
+  output-dir: _build
+  preview:
+    port: 3456 # use the same port instead of a new one each time
+    browser: true
+
+book:
+  title: "Python for Finance"
+  subtitle: "2024 Edition"
+  author: "Michael Rossetti"
+  #date: de
+  chapters:
+    - index.qmd
+    - intro.qmd
+    - summary.qmd
+    - references.qmd
+
+bibliography: references.bib
+
+format:
+  html:
+    theme: cosmo
+  pdf:
+    documentclass: scrreprt

docs/index.qmd

@@ -0,0 +1,5 @@
+# Preface {.unnumbered}
+
+This is a Quarto book.
+
+To learn more about Quarto books visit <https://quarto.org/docs/books>.

docs/intro.qmd

@@ -0,0 +1,5 @@
+# Introduction
+
+This is a book created from markdown and executable code.
+
+See @knuth84 for additional discussion of literate programming.

docs/references.bib

@@ -0,0 +1,19 @@
+@article{knuth84,
+  author = {Knuth, Donald E.},
+  title = {Literate Programming},
+  year = {1984},
+  issue_date = {May 1984},
+  publisher = {Oxford University Press, Inc.},
+  address = {USA},
+  volume = {27},
+  number = {2},
+  issn = {0010-4620},
+  url = {https://doi.org/10.1093/comjnl/27.2.97},
+  doi = {10.1093/comjnl/27.2.97},
+  journal = {Comput. J.},
+  month = may,
+  pages = {97–111},
+  numpages = {15}
+}
+
+

docs/references.qmd

@@ -0,0 +1,4 @@
+# References {.unnumbered}
+
+::: {#refs}
+:::

docs/requirements.txt

@@ -0,0 +1,16 @@
+
+
+
+# packages to facilitate quarto execution of IPYNB notebooks, with execute: true
+# ... or if you use jupyter: python3 to execute python inside code blocks in your .qmd file
+#jupyter
+
+
+# cached execution:
+# https://quarto.org/docs/projects/code-execution.html#cache
+#jupyter-cache
+
+
+# packages required by any python code / notebooks:
+#numpy
+#matplotlib

docs/summary.qmd

@@ -0,0 +1,3 @@
+# Summary
+
+In summary, this book has no content whatsoever.