Merge pull request #17 from premAI-io/framework-v1

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+# Review checklist
+
+> Don't worry about satisfying all items, it's fine to open a (draft) PR.
+
+- [ ] chapter content
+  + [ ] only one top-level `# h1-Title`
+  + [ ] summary (e.g. table or TL;DR overview), no need for an explicit `## Summary/Introduction` title or equivalent
+  + [ ] main content focus: recent developments in open source AI
+    + general context/background (brief)
+    + current pros/cons
+    + in-depth insights (not yet widely known)
+  + [ ] likely `## Future` developments
+  + [ ] end with `{{ comments }}`
+- [ ] appropriate citations
+  + [ ] BibTeX references
+  + [ ] Glossary terms
+  + [ ] cross-references (figures/chapters)
+  + [ ] (if `new-chapter.md`), add `_toc.yml` entry & `index.md` table row
+  + [ ] If CI URL checks have false-positives, append to `_config.yml:sphinx.config.linkcheck*`
+- [ ] images & data not committed to this repo (e.g. use https://github.com/premAI-io/static.premai.io instead)

.github/workflows/pages.yml

@@ -8,7 +8,7 @@ permissions:
   contents: read
   pages: write
   id-token: write
-concurrency: {group: "pages", cancel-in-progress: true}
+concurrency: {group: "${{ github.ref }}-pages", cancel-in-progress: true}
 jobs:
   build:
     runs-on: ubuntu-latest

_config.yml

@@ -2,11 +2,12 @@
 title: State of Open Source AI Book
 author: Prem AI
 copyright: 2023 CC-BY-4.0 (text) & Apache-2.0 (code)
-logo: assets/logo.png
+logo: https://static.premai.io/logo.png
 repository:
   url: https://github.com/premAI-io/state-of-open-source-ai
   branch: main
 only_build_toc_files: true
+exclude_patterns: [.github/*]
 html:
   baseurl: http://localhost:8000
   favicon: assets/favicon.ico
@@ -48,6 +49,7 @@ sphinx:
     - https://github.com/imaurer/awesome-decentralized-llm#.*
     - https://gist.github.com/veekaybee/be375ab33085102f9027853128dc5f0e#.*
     - https://github.com/premAI-io/state-of-open-source-ai # TODO: remove
+    - https://contrib.rocks # TODO: remove
     linkcheck_allowed_redirects:
       https://codespaces.new/.*: https://github.com/login.*
       https://youtu.be/.*: https://www.youtube.com/watch\?v=.*&feature=youtu.be

index.md

@@ -65,8 +65,16 @@ We understand that the current open source ecosystem is moving at light-speed. T
   ```
   ````
 
+(index#formatting)=
+
 ### Formatting
 
+````{note}
+```{eval-rst}
+Don't worry about making it perfect, it's fine to open a (`draft <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests>`_) PR and `allow edits from maintainers <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_ to fix it |:heart:|
+```
+````
+
 - [Quickstart](https://jupyterbook.org/en/stable/reference/cheatsheet.html)
 - [Full reference](https://jupyterbook.org/en/stable/content/myst.html)
 - Create a new chapter:
@@ -77,17 +85,25 @@ We understand that the current open source ecosystem is moving at light-speed. T
 
   ```{figure-md} fig-ref
   :class: margin-caption
-  ![alt-text](assets/logo.png){width=200px align=left}
+  ![alt-text](https://static.premai.io/logo.png){width=200px align=left}
 
   This is a **figure caption** *in the margin*, vis [jupyterbook#markdown-figures](https://jupyterbook.org/en/stable/content/figures.html#markdown-figures)
   ```
 
-  - [inline ref](fig-ref)
-  - numbered ref: {numref}`fig-ref`
-  - custom ref: {numref}`Figure {number} with caption "{name}" <fig-ref>`
+  + [inline ref](fig-ref)
+  + numbered ref: {numref}`fig-ref`
+  + custom ref: {numref}`Figure {number} with caption "{name}" <fig-ref>`
+  + please use https://github.com/premAI-io/static.premai.io to host images & data
+
+- [](glossary) term: {term}`GPU`
+  + custom inline text: {term}`GPUs <GPU>`
+- [BibTeX](https://jupyterbook.org/en/stable/tutorials/references.html#add-your-references) `references.bib` citation: {cite}`python`
 
-- Glossary term: {term}`GPU`
-- `references.bib` citation: {cite}`python`
+% comment lines (not rendered) are prefixed with a "%"
+
+### Contributors
+
+{{ '[![](https://contrib.rocks/image?repo=' + '/'.join(repo_url.split('/')[-2:]) + ')](' + repo_url + '/graphs/contributors)' }}
 
 ## Conclusion
 
@@ -105,14 +121,17 @@ At Prem we are on a journey to make this possible, with a focus on developer exp
 
 ## Glossary
 
+%TODO: define all these & use them where appropriate
+
 ```{glossary}
 :sorted:
+Foundation model
 Evaluation
 Auto-regressive language model
-decoder-style transformer
+Decoder-style transformer
 Tokens
 [GPU](https://en.wikipedia.org/wiki/Graphics_processing_unit)
-    Graphics Processing Unit: hardware originally designed to accelerate computer image processing, but now often repurposed for [embarrassingly parallel](https://en.wikipedia.org/wiki/Embarrassingly_parallel) computational tasks in machine learning.
+  Graphics Processing Unit: hardware originally designed to accelerate computer image processing, but now often repurposed for [embarrassingly parallel](https://en.wikipedia.org/wiki/Embarrassingly_parallel) computational tasks in machine learning.
 
 A100, V100, H100
 Vector

references.md

@@ -38,6 +38,8 @@ Couldn't decide which chapter(s) these links are related to. They're mostly abou
 - "RetrievalQA with LLaMA 2 70b & Chroma DB" (nothing new, but this guy does a lot of experiments if you wanna follow him) https://youtu.be/93yueQQnqpM
 - "[WiP] build MLOps solutions in Rust" https://github.com/nogibjj/rust-mlops-template
 
+## BibTeX references (TODO: use this more -- see [guide](index#formatting))
+
 ```{bibliography}
 :style: unsrt
 ```

requirements.txt

@@ -1,2 +1,4 @@
 jupyter-book
 sphinxemoji
+# TODO: remove after https://github.com/executablebooks/jupyter-book/pull/2048
+docutils!=0.18.*,!=0.19.*,!=0.20.0