Skip to content

Commit

Permalink
Initial commit
Browse files Browse the repository at this point in the history
ChrisCompton authored Sep 29, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
0 parents commit f0438f8
Showing 21 changed files with 1,360 additions and 0 deletions.
61 changes: 61 additions & 0 deletions .github/workflows/static.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
name: Deploy Demo Notebook

on:
push:
branches: ["main"]
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: "pages"
cancel-in-progress: false

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out repository code.
uses: actions/checkout@v3
- name: Check environment.
run: |
ls -ltra
python --version
pip --version
- name: Install dependencies.
run: |
pip install -r requirements.txt
- name: Build presentations.
run: |
npm install -g @marp-team/marp-cli
python scripts/marp.py
- name: Run python script.
run: |
mkdocs build
- name: Package site.
uses: actions/upload-artifact@v4
with:
name: notebook-site
path: |
site
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Download a single artifact
uses: actions/download-artifact@v4
with:
name: notebook-site
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: '.'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
9 changes: 9 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
*.pyc
*.sqlite
.DS_Store
.idea/
.venv/
__pycache__/
*.egg-info/
site/
.vscode/
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2024 D.C. Compton

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
61 changes: 61 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
> [!CAUTION]
> I'm actively working on the notebook, particularly marp support.
> **I recommend avoiding marp setup for now.**
# Notebook

This is my approach to building a local notebook (or one for github-pages), that can be used in day-to-day work.

## Setup

```shell
python -m venv ./.venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

## mkdocs

To execute the mkdocs notebook for development of content:

```shell
mkdocs serve
```
The build the site for rendering through a web server, or to use with the FastAPI runner:

```shell
mkdocs build
```

## FastAPI

A minimal FastAPI script (`main.py`) is provided to serve the site directory after the site is built.

```shell
source .venv/bin/activate
mkdocs build
fastapi dev main.py
```

---

## For marp support

> [!WARNING]
> **NOT READY TO USE YET!**
If you use this, create a feature branch to test. This will edit your content, and could break things. I am working on improving, but it will be a while before I get back to it.

```shell
source .venv/bin/activate
npm install -g @marp-team/marp-cli
python scripts/marp.py
```

Encoding images for CSS:

- If you want to add new theme images, put them in the `marp/images/` directory.
- Remove the images from the end of `marp/notebook.css`.
- You must replace the `content.png` and `topic.png` files with your own.
- You can execute `python/encode.py >> marp/notebook.css` to append the encoded images to the css.

118 changes: 118 additions & 0 deletions docs/credits.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@

## MkDocs

=== "Acknowledgment"

This project uses MkDocs to manage and produce the content and site.

- [MkDocs](https://www.mkdocs.org/)
- [GitHub Project](https://github.com/mkdocs/mkdocs)

> Copyright © 2014, Tom Christie. All rights reserved.

=== "License"

```
Copyright © 2014-present, Tom Christie. All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
```

---

## Material for MkDocs

=== "Acknowledgment"

This project uses the Material for MkDocs theme as the basis of the notebook.

- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
- [GitHub Project](https://github.com/squidfunk/mkdocs-material)

> Copyright (c) 2016-2024 Martin Donath <[email protected]>

=== "License"

```
Copyright (c) 2016-2024 Martin Donath <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
```

---

## Marp Markdown Presentation Ecosystem

=== "Acknowledgment"

This project uses Marp to create the HTML and PDF presentations.

- [Marp](https://marp.app/)
- [GitHub Project](https://github.com/marp-team/marp)

> Copyright (c) 2018-2023 Marp team ([email protected])

=== "License"

```
MIT License

Copyright (c) 2018-2023 Marp team ([email protected])

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
2 changes: 2 additions & 0 deletions docs/demo/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
*.html
*.pdf
26 changes: 26 additions & 0 deletions docs/demo/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
marp: true
theme: notebook
---

<!-- _class: topic -->

# Demo Presentation


---

# Slide 2 Title

- Content Here
- More content

---

# Thank you!



<div id="slide_menu" class="grid cards" markdown>
- [:fontawesome-brands-html5: __HTML__ Slides: Slides](index_slides.html)
- [:fontawesome-solid-file-pdf: __PDF__ Document: Slides](index_slides.pdf)</div>
38 changes: 38 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@


# Welcome to the Notebook

For full documentation visit [chriscompton.github.io/notebook](https://chriscompton.github.io/notebook/).

## MkDocs Commands

* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.

## Marp Commands

* `python scripts/marp.py` - Generate presentations when front matter has `marp: true`

!!! note

The **marp script will alter your markdown files** to add buttons at the bottom of the page for
HTML and PDF. If you change `marp: false`, it will cause the script to remove the links and
the generated files.

## Project layout

mkdocs.yml # The configuration file.
scripts/
marp.py # Scans for markdown files requiring presentations.
encode.py # Converts the png template images to css embeddable images.
marp/
notebook/
image/ # Has the png background images for presentations.
notebook.css # The CSS file used for presentation formatting.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.

## Formatting

You can find great documentation on formatting content at the [mkdocs-material reference](https://squidfunk.github.io/mkdocs-material/reference/).
1 change: 1 addition & 0 deletions docs/static/.pages
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
hide: true
31 changes: 31 additions & 0 deletions docs/static/css/adjust.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@

/* Sets a common highlight color
.md-content a {
color: #00833d;
}
/* Sets a common background color */
.md-header,
.md-tabs {
background-color: #00833d;
}

/* Adjusts the search result content */
.md-search-result .md-typeset {
display: -webkit-box;
-webkit-line-clamp: 3;
line-clamp: 3;
-webkit-box-orient: vertical;
max-height: 200px;
}

/* Adjusts the width of the content to help with larger mermaid diagrams */
.md-grid {
max-width: unset;
width: 100%;
}

div.mermaid {
width: unset !important;
width: 100%;
}
Empty file added docs/static/js/main.js
Empty file.
10 changes: 10 additions & 0 deletions main.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount("/", StaticFiles(directory="./site", html=True), name="notebook")

# mkdocs build
# pip install "fastapi[standard]"
# fastapi dev main.py
Binary file added marp/notebook/images/content.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added marp/notebook/images/topic.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
790 changes: 790 additions & 0 deletions marp/notebook/notebook.css

Large diffs are not rendered by default.

67 changes: 67 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
site_name: Notebook
# docs_dir: ../your_docs_dir
repo_url: https://github.com/ChrisCompton/notebook
repo_name: ChrisCompton/notebook
edit_uri: blob/main/docs/
theme:
name: material
palette:
primary: green
features:
- content.action.edit
- content.action.view
- content.code.annotate
- content.code.copy
- content.tabs.link
- content.tooltips
- navigation.tabs
- navigation.top
- search.highlight
- toc.follow


plugins:
- search
- awesome-pages

highlightjs: true
hljs_languages:
- yaml
- python
- sql


extra_css:
- /static/css/adjust.css
extra_javascript:
- /static/js/main.js


markdown_extensions:
- attr_list
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- md_in_html
- admonition
- pymdownx.details
- footnotes
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
clickable_checkbox: true
custom_checkbox: true


exclude_docs: |
__*.md
draft_docs: |
DRAFT_*.md
extra:
generator: false
12 changes: 12 additions & 0 deletions requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
fastapi==0.115.0
mkdocs==1.6.1
mkdocs-awesome-pages-plugin==2.9.3
mkdocs-get-deps==0.2.0
mkdocs-git-revision-date-localized-plugin==1.2.9
mkdocs-material==9.5.36
mkdocs-material-extensions==1.3.1
mkdocs-mermaid2-plugin==1.1.1
mkdocs-render-swagger-plugin==0.1.2
mkdocs-table-reader-plugin==3.1.0
PyYAML==6.0.2
uvicorn==0.30.6
3 changes: 3 additions & 0 deletions scripts/config.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
markdown_source_path = 'docs'
marp_theme_path = 'marp/notebook'
marp_theme_image_path = 'marp/notebook/images'
24 changes: 24 additions & 0 deletions scripts/encode.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import os
import base64

import config as cfg

def encode_images_to_base64(directory):
for filename in os.listdir(directory):
if filename.endswith('.png'):
file_path = os.path.join(directory, filename)
with open(file_path, 'rb') as image_file:
encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
if filename == 'topic.png':
class_name = "section.topic,section.intro"
else:
class_name = "section"

print(f"/* {filename} */")
print(f"{class_name} {{ background-image: url(data:image/png;base64,{encoded_string}); }} \n")

# Example usage
encode_images_to_base64(cfg.marp_theme_image_path)

# delete the existing images from the marp/notebook.css file
# python scripts/encode.py >> marp/notebook/notebook.css
75 changes: 75 additions & 0 deletions scripts/marp.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@

import os
import subprocess
import yaml

import config as cfg

def process_markdown_files(base_path):
for root, _, files in os.walk(base_path):
for file in files:
if file.endswith('.md'):
md_file = os.path.join(root, file)
print(f"Processing {md_file}")
with open(md_file, 'r', encoding="utf8") as f:
content = f.read()
if content.startswith('---'):
end = content.find('---', 3)
if end != -1:
front_matter = yaml.safe_load(content[3:end])
if 'marp' in front_matter:
if front_matter.get('marp') == True:
remove_links(md_file)
generate_slides(md_file)
append_links(md_file)
elif front_matter.get('marp') == False:
remove_generated_files(md_file)
remove_links(md_file)

def run_marp(format, input, output):
if format in ['html','pdf']:
cmd = ['marp', '--allow-local-files', f'--{format}','--theme-set', cfg.marp_theme_path, '--output', output, input]
# cmd = ['marp', '--output', output, input]
print(" ".join(cmd))
subprocess.run(cmd)
# subprocess.run(cmd, shell=True, check=True)
else:
print("Bad format type. Allowed: html or pdf")

def generate_slides(md_file):
base_name = os.path.splitext(md_file)[0]
html_file = f"{base_name}_slides.html"
pdf_file = f"{base_name}_slides.pdf"
run_marp('html', md_file, html_file)
run_marp('pdf', md_file, pdf_file)

def append_links(md_file):
base_name = os.path.splitext(os.path.basename(md_file))[0]
print("FILE: ",base_name)
html_file = f"{base_name}_slides.html"
pdf_file = f"{base_name}_slides.pdf"
links = f"""\n<div id="slide_menu" class="grid cards" markdown>\n- [:fontawesome-brands-html5: __HTML__ Slides: Slides]({html_file})\n- [:fontawesome-solid-file-pdf: __PDF__ Document: Slides]({pdf_file})</div>"""
with open(md_file, 'a') as f:
f.write(links)

def remove_generated_files(md_file):
base_name = os.path.splitext(md_file)[0]
html_file = f"{base_name}_slides.html"
pdf_file = f"{base_name}_slides.pdf"
if os.path.exists(html_file):
os.remove(html_file)
if os.path.exists(pdf_file):
os.remove(pdf_file)

def remove_links(md_file):
with open(md_file, 'r', encoding="utf8") as f:
lines = f.readlines()
with open(md_file, 'w', encoding="utf8") as f:
for line in lines:
if not line.startswith('<div id="slide_menu"') and not line.startswith('- [:fontawesome-brands-html5: __HTML__ Slides: Slides]') and not line.startswith('- [:fontawesome-solid-file-pdf: __PDF__ Document: Slides]'):
f.write(line)

# Example usage
print (f"Processing markdown files from: {cfg.markdown_source_path}")
process_markdown_files(cfg.markdown_source_path)
print ("Done processing markdown files")
11 changes: 11 additions & 0 deletions test_main.http
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Test your FastAPI endpoints

GET http://127.0.0.1:8000/
Accept: application/json

###

GET http://127.0.0.1:8000/hello/User
Accept: application/json

###

0 comments on commit f0438f8

Please sign in to comment.