From 9dcfff9cb9f9585ba3d47fc48994a1edee0a0db5 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 3 Mar 2022 16:50:32 -0800 Subject: [PATCH 1/9] Add pre-commit hooks --- .github/ISSUE_TEMPLATE/team-meeting.md | 22 +- .github/workflows/create-meeting-issue.yml | 4 +- .github/workflows/trigger-docs-build.yml | 2 +- .pre-commit-config.yaml | 27 ++ docs/Makefile | 2 +- docs/_static/custom.css | 2 +- docs/about.md | 26 +- docs/communication.md | 1 + docs/conf.py | 8 +- docs/feature-vote.md | 6 +- docs/gallery.yml | 2 +- docs/index.md | 2 - docs/meetings/2021.md | 378 ++++++++++--------- docs/team.md | 4 +- docs/team_panels_code.txt | 1 - docs/tools.md | 53 ++- docs/updates/2020-02-25-hello-world.md | 16 +- docs/updates/2020-08-07-announce-book.md | 12 +- docs/updates/2021-06-18-update-toc.md | 2 +- docs/updates/2021-06-5-release-jb-v0.11.1.md | 4 +- requirements.txt | 2 +- 21 files changed, 309 insertions(+), 267 deletions(-) create mode 100644 .pre-commit-config.yaml diff --git a/.github/ISSUE_TEMPLATE/team-meeting.md b/.github/ISSUE_TEMPLATE/team-meeting.md index 5210807..cddebc4 100644 --- a/.github/ISSUE_TEMPLATE/team-meeting.md +++ b/.github/ISSUE_TEMPLATE/team-meeting.md @@ -1,10 +1,6 @@ ---- -name: Team Meeting 📅 -about: A team meeting -title: 'EBP Team Meeting - {{ MONTH }}' -labels: meeting -assignees: '' ---- +______________________________________________________________________ + +## name: Team Meeting 📅 about: A team meeting title: 'EBP Team Meeting - {{ MONTH }}' labels: meeting assignees: '' Hello @executablebooks/ebpteam! This is an issue to track the next Executable Books team meeting! Here's some relevant information: @@ -16,11 +12,11 @@ If you'd like to discuss something at the meeting, please add an item to the age ### Before the meeting -- [ ] Update dates and make sure HackMD information is correct. -- [ ] Team members add agenda items. - +- \[ \] Update dates and make sure HackMD information is correct. +- \[ \] Team members add agenda items. + ### After the meeting -- [ ] Turn any follow-ups into issues/comments/etc. -- [ ] Copy the meeting notes to the docs. -- [ ] Remove notes and clean up HackMD. +- \[ \] Turn any follow-ups into issues/comments/etc. +- \[ \] Copy the meeting notes to the docs. +- \[ \] Remove notes and clean up HackMD. diff --git a/.github/workflows/create-meeting-issue.yml b/.github/workflows/create-meeting-issue.yml index 54d151a..40cd543 100644 --- a/.github/workflows/create-meeting-issue.yml +++ b/.github/workflows/create-meeting-issue.yml @@ -5,7 +5,7 @@ on: # 25th day of the month, so we have a bit of lead time before the next meeting - cron: '0 0 25 * *' workflow_dispatch: - + jobs: create-team-issue: runs-on: ubuntu-latest @@ -15,4 +15,4 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: - filename: .github/ISSUE_TEMPLATE/team-meeting.md \ No newline at end of file + filename: .github/ISSUE_TEMPLATE/team-meeting.md diff --git a/.github/workflows/trigger-docs-build.yml b/.github/workflows/trigger-docs-build.yml index 1dc40e1..a2f80e7 100644 --- a/.github/workflows/trigger-docs-build.yml +++ b/.github/workflows/trigger-docs-build.yml @@ -6,7 +6,7 @@ on: # every day at 1:00 - cron: '0 1 * * *' workflow_dispatch: - + jobs: docs: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..2ef90b9 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,27 @@ +# Install pre-commit hooks via +# pre-commit install + +exclude: > + (?x)^( + \.vscode/settings\.json| + )$ +repos: + + - repo: git://github.com/pre-commit/pre-commit-hooks + rev: v4.1.0 + hooks: + - id: check-toml + - id: check-json + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + + - repo: https://github.com/psf/black + rev: 22.1.0 + hooks: + - id: black + + - repo: https://github.com/executablebooks/mdformat + rev: 0.7.13 + hooks: + - id: mdformat diff --git a/docs/Makefile b/docs/Makefile index 8533f57..ef45bc1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,4 +20,4 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) live: - sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt \ No newline at end of file + sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt diff --git a/docs/_static/custom.css b/docs/_static/custom.css index d671601..0512ed1 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -9,4 +9,4 @@ ul.postlist > li > p:first-child { .landing-grid .sd-card-header { background-color: #f3772638; -} \ No newline at end of file +} diff --git a/docs/about.md b/docs/about.md index 6c76a41..e10c50e 100644 --- a/docs/about.md +++ b/docs/about.md @@ -24,20 +24,20 @@ professional computational narratives (books, lecture series, articles, etc.) using open source tools. We want users in the scientific, academic, and data science communities to be able to do the following: -* **Write their content in either markdown text files, or Jupyter Notebooks**. +- **Write their content in either markdown text files, or Jupyter Notebooks**. These files include rich content - outputs from running code, references and cross-references, equations, etc. -* **Execute content and cache the results**. Intelligent caching means +- **Execute content and cache the results**. Intelligent caching means that only modified code cells are re-run. -* **Combine cached outputs with content files with a document model**. Using +- **Combine cached outputs with content files with a document model**. Using the excellent [Sphinx](https://www.sphinx-doc.org/en/master/) documentation stack, documents can include many features for publishing, such as equations, cross-references, and citations. -* **Build interactive HTML or publication-quality PDF outputs**. Sometimes +- **Build interactive HTML or publication-quality PDF outputs**. Sometimes users wish to create rich and interactive websites, other times they want to send a high-quality PDF to a publisher. This system will treat both as equal citizens. -* **Control everything above with a simple command-line interface**. Most +- **Control everything above with a simple command-line interface**. Most users should not have to know anything about Sphinx, caching, etc. A simple user interface will hide most of the complexity of this process. @@ -50,28 +50,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -* **Give equal support to casual users and power users**. Complicating the feature +- **Give equal support to casual users and power users**. Complicating the feature space to support a "power user feature" should be done with great care. -* **Build modular components that are useful elsewhere**. Rather than building +- **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -* **Use pre-existing technology where possible**. Rather than re-inventing +- **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -* **Use pre-existing standards where possible**. In the event that we must +- **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -* **Contribute improvements upstream**. Where we utilize pre-existing tools, +- **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -* **Design for the future**. While we have a bit of funding now, it won't last +- **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -* **Users should not need to know anything about the build system**. If they +- **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, and so on should not be a requirement. They should only need to use a simple tool to control the process. -* **Don't try to do everything**. Focus our tools on publishing +- **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. Browse the rest of this site for more information about what we're working diff --git a/docs/communication.md b/docs/communication.md index 4c612e2..8cec0e5 100644 --- a/docs/communication.md +++ b/docs/communication.md @@ -12,6 +12,7 @@ This is open to anybody, and is a space where people can ask questions and help Please feel free to provide support, advice, etc to anybody on this forum. (comms:issues)= + ## GitHub Issues For conversations around specific actions, tasks, features, etc, we use GitHub issues in each repository. diff --git a/docs/conf.py b/docs/conf.py index 8b67f22..db93b7c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -189,10 +189,10 @@ def build_gallery(app: Sphinx): ) grid_items = "\n".join(grid_items) -# :column: text-center col-6 col-lg-4 -# :card: +my-2 -# :img-top-cls: w-75 m-auto p-2 -# :body: d-none + # :column: text-center col-6 col-lg-4 + # :card: +my-2 + # :img-top-cls: w-75 m-auto p-2 + # :body: d-none panels = f""" ``````{{grid}} 1 2 3 3 diff --git a/docs/feature-vote.md b/docs/feature-vote.md index dbc1894..2bb1421 100644 --- a/docs/feature-vote.md +++ b/docs/feature-vote.md @@ -1,12 +1,13 @@ (feature-note)= + # Feature voting board You can help us to prioritise development of new features by leaving a [👍 reaction](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) on the first comment of any `enhancement` issue. -Below is a list of all current enhancement issues from our core repositories,[^a] ordered by 👍 +Below is a list of all current enhancement issues from our core repositories,\[^a\] ordered by 👍 Click the `+` to see more details. -[^a]: The data in this table is updated every day. +\[^a\]: The data in this table is updated every day.
@@ -16,6 +17,7 @@ Click the `+` to see more details.
+ diff --git a/docs/gallery.yml b/docs/gallery.yml index afe44b1..386acc0 100644 --- a/docs/gallery.yml +++ b/docs/gallery.yml @@ -147,7 +147,7 @@ image: https://raw.githubusercontent.com/rafneta/CienciaDatosPythonCIDE/master/docs/logo.jpg website: https://rafneta.github.io/CienciaDatosPythonCIDE/intro.html - name: "Development Data Partnership" - repository: + repository: image: https://raw.githubusercontent.com/datapartnership/welcome/master/images/logo.png website: https://docs.datapartnership.org - name: "OpenPifPaf Guide" diff --git a/docs/index.md b/docs/index.md index 4a4d019..6b6bdb0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,7 +39,6 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co ::: :::: - ## Acknowledgements :::{image} https://pbs.twimg.com/profile_images/1226944724365447169/MzFpwY5P_400x400.png @@ -50,7 +49,6 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co The Executable Books Project is supported by several institutions and members of open source projects. In particular, many thanks to the [Sloan Foundation](https://sloan.org) which [provides support for the Executable Books Project](https://sloan.org/grant-detail/9231). - ```{toctree} :maxdepth: 2 :caption: Get Involved diff --git a/docs/meetings/2021.md b/docs/meetings/2021.md index a0a0e0b..7a273c5 100644 --- a/docs/meetings/2021.md +++ b/docs/meetings/2021.md @@ -16,19 +16,18 @@ ### Team updates - -- [sphinx-exercise] has been re-factored to make the extension more maintainable. - - https://github.com/executablebooks/sphinx-exercise/pull/37 - - no major user facing changes (except some style updates to output) - - focus: use sphinx internals and AST as much as possible - - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase - - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) - - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html - - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: - - custom styling - - custom options - - ref and numref integration - - autonumbering of nodes (i.e. numref) +- \[sphinx-exercise\] has been re-factored to make the extension more maintainable. + - https://github.com/executablebooks/sphinx-exercise/pull/37 + - no major user facing changes (except some style updates to output) + - focus: use sphinx internals and AST as much as possible + - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase + - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) + - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html + - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: + - custom styling + - custom options + - ref and numref integration + - autonumbering of nodes (i.e. numref) - Rowan - Javascript PR merges in - Low hanging fruit is done on the JS side @@ -64,49 +63,49 @@ ### Team updates - Chris H - - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 - - Focusing most of my time trying to document things + un-block people - - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it + - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 + - Focusing most of my time trying to document things + un-block people + - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it - Steve P - - Progress on thebe: - - Major styles bug fixed - - First cut of status and activate button out - - Changed the docs & examples to use latest build - Thanks to recent RTD changes - - Started a Jupyterlite example - have JupyterLiteServer running in browser - - Next Steps: - - Test & Release - - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) - - Refactoring - - separate jquery layer from low level api (opens up more options for integration) - - document jquery and low level api - - follow through on rename - - Include Jupyterlite kernel option (and generalise) - - Tackle enhancements from Chris S. in thebe / sphinx-thebe + - Progress on thebe: + - Major styles bug fixed + - First cut of status and activate button out + - Changed the docs & examples to use latest build - Thanks to recent RTD changes + - Started a Jupyterlite example - have JupyterLiteServer running in browser + - Next Steps: + - Test & Release + - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) + - Refactoring + - separate jquery layer from low level api (opens up more options for integration) + - document jquery and low level api + - follow through on rename + - Include Jupyterlite kernel option (and generalise) + - Tackle enhancements from Chris S. in thebe / sphinx-thebe - Matt M - - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 - - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing - - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. - - General agreement that this would be useful :-) - - Added LaTeX support to sphinx-proof - - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html - - Semantic Admonitions! + - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 + - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing + - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. + - General agreement that this would be useful :-) + - Added LaTeX support to sphinx-proof + - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html + - Semantic Admonitions! - Chris S - - +1 for `sphinx-basic-ng` and merging focus of themes - - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 - - Made PoC PR to nbclient and nbformat - - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks - - But will it go stale 😬 - - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 - - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe - - Also added merging streams in myst-nb - - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 - - Working with `cpitclaudel` to add "proper" docutils support for myst-parser - - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) - - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" + - +1 for `sphinx-basic-ng` and merging focus of themes + - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 + - Made PoC PR to nbclient and nbformat + - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks + - But will it go stale 😬 + - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 + - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe + - Also added merging streams in myst-nb + - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 + - Working with `cpitclaudel` to add "proper" docutils support for myst-parser + - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) + - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" - Rowan - - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. - - Need to get back to myst in js work, next week! - - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere + - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. + - Need to get back to myst in js work, next week! + - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere ### Agenda items @@ -115,18 +114,19 @@ - switch to new GitHub project boards? Demo here: https://github.com/orgs/executablebooks/projects/9/views/1 #### Community proposal doc + - Issue for comments/discussion: https://github.com/executablebooks/meta/issues/493 - Proposal text: https://hackmd.io/@choldgraf/HkgAIHtQY - What are some major next steps? - - Investigate the major steps we'd need to take to integrate with the Jupyter community - - Sticking points? - - We'll need to demonstrate that we have a good maintainability story - - Might have questions around the different parts of EBP - - Start to get feedback in the Jupyter ecosystem - - Threads in the discourse + the governance repo - - Talk to stakeholders in that community and see if there are any things we should think about it - - Crystallize the community strategy doc into some concrete next steps - - Decide on an order of operations for things to tackle + - Investigate the major steps we'd need to take to integrate with the Jupyter community + - Sticking points? + - We'll need to demonstrate that we have a good maintainability story + - Might have questions around the different parts of EBP + - Start to get feedback in the Jupyter ecosystem + - Threads in the discourse + the governance repo + - Talk to stakeholders in that community and see if there are any things we should think about it + - Crystallize the community strategy doc into some concrete next steps + - Decide on an order of operations for things to tackle ## September 1st 2021 @@ -137,7 +137,7 @@ If you are joining the team video meeting, sign in below so we know who was here - Rowan Cockett / Curvenote / rowanc1 - Matt McKay / ANU / mmcky - Chris Holdgraf / 2i2c / choldgraf -- Damián Avila / 2i2c / damianavila +- Damián Avila / 2i2c / damianavila - Chris Sewell / EPFL / chrisjsewell ### Reports, updates, and celebrations @@ -145,55 +145,61 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - THEBE: - - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing - - Opened(opening) tickets on activity board for dicussion - - Refactoring, improving test coverage and docs - - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection + + - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing + - Opened(opening) tickets on activity board for dicussion + - Refactoring, improving test coverage and docs + - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection - Some blog post about MyST in my personal blog (Damián) - - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) - - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) - - Eventually, a part 3 with some coding experiment/stuff + + - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) + - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) + - Eventually, a part 3 with some coding experiment/stuff - Sphinx 4 Upgrade (Matt) - - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 - - Action: Cut a new release right after merge + + - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 + - Action: Cut a new release right after merge - ReadTheDocs integration (Chris S) - - That is now working - - PR is open - just waiting on documenting it up - - Action: Needs Doc Update + + - That is now working + - PR is open - just waiting on documenting it up + - Action: Needs Doc Update ### Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - Steve: Thebe directions, and future focus - - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? - - A lot of issues in the repository - - Was a JupyterCon Sprint + a board from that - - Would like to do a bit of planning about what issues etc to tackle next - - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions - - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest + + - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? + - A lot of issues in the repository + - Was a JupyterCon Sprint + a board from that + - Would like to do a bit of planning about what issues etc to tackle next + - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions + - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest - Rowan: Thoughts on how to move JS-Myst forward (dev branch?) - - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. - - Might just be an off month?! - - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? - - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. - - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. + + - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. + - Might just be an off month?! + - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? + - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. + - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. - Chris H: in-line markdown execution? - - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 - - The difficulty is in the specification - - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) - - An easy first step would be to do "read only inline markdown" - - This is a really popular feature of RMarkdown / Quarto Markdown - - Can you start with the restriction "we should be able to still run every code cell" - - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` - - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. - - You'd then do the execution, and at the end of the time that + - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 + - The difficulty is in the specification + - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) + - An easy first step would be to do "read only inline markdown" + - This is a really popular feature of RMarkdown / Quarto Markdown + - Can you start with the restriction "we should be able to still run every code cell" + - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` + - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. + - You'd then do the execution, and at the end of the time that # 05th August 2021 @@ -210,94 +216,107 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - Chris Sewell - - Sphinx Designs - better designed panels, will come into jupyter book at some point - - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten - - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! - - There is also multi-processing on the notebooks! 💥 - - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) - - Javascript! - - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) - - There are same directives and roles from Python - - Same arguments/content - - This is now over to the vscode extension - - MyST as a "standard" - - What roles, directives, blocks to we need that are copied over in another language - - We should get the critical ones in a list somewhere! - - Forming specs in a collaborative way (Identify Good Tools for this?) - -- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) - - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) - - Adding a directive that is a question, and then how do you add code? - - Directive at the top level and then code and exercise. - - Violates the core design of the Jupyter Notebook -- nested code cells - - Got rid of "nested" concepts - - So how do you have "Gated" directive (open/close) around a few code cells - - This is more compliant with other tools like Jupytext - - Not sure if there is a Gated directive, or prior art in the Sphinx world? - - Other options: - - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) - - Glue? (currently restricted to python, cather than cellId or something) - - Similar ideas playing with at Curvenote! (copy/paste) - - Consideration is mostly from an authorship perspective + + - Sphinx Designs - better designed panels, will come into jupyter book at some point + - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten + - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! + - There is also multi-processing on the notebooks! 💥 + - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) + - Javascript! + - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) + - There are same directives and roles from Python + - Same arguments/content + - This is now over to the vscode extension + - MyST as a "standard" + - What roles, directives, blocks to we need that are copied over in another language + - We should get the critical ones in a list somewhere! + - Forming specs in a collaborative way (Identify Good Tools for this?) + +- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) + + - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) + - Adding a directive that is a question, and then how do you add code? + - Directive at the top level and then code and exercise. + - Violates the core design of the Jupyter Notebook -- nested code cells + - Got rid of "nested" concepts + - So how do you have "Gated" directive (open/close) around a few code cells + - This is more compliant with other tools like Jupytext + - Not sure if there is a Gated directive, or prior art in the Sphinx world? + - Other options: + - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) + - Glue? (currently restricted to python, cather than cellId or something) + - Similar ideas playing with at Curvenote! (copy/paste) + - Consideration is mostly from an authorship perspective - Steve Purves: Thebe - - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development - - PR for a small feature - progress indicator - - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better - - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on - - Next up: - - Connecting to many different kernals, and having some basic management on that! + + - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development + - PR for a small feature - progress indicator + - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better + - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on + - Next up: + - Connecting to many different kernals, and having some basic management on that! - Rowan: MyST in JS - - Working on myst in JS. Migrating work over to docutils and cleaning up along the way - - Still basics of various libraries - - - 10 or so PRs up at the moment! - - Basics: - - sub/sup/abbr - - internationalization? [each role/directive has a different name] - - Can generate various dicts to export - - Admonitions - - Math - - amsmath, dollar, math directive - - Figures - - Referencing/numbering PR - - numref/eq/ref - - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS - - How are we working with styles? - - There is some copying back and forth of the .css + + - Working on myst in JS. Migrating work over to docutils and cleaning up along the way + + - Still basics of various libraries + + - 10 or so PRs up at the moment! + + - Basics: + - sub/sup/abbr + - internationalization? \[each role/directive has a different name\] + - Can generate various dicts to export + - Admonitions + - Math + - amsmath, dollar, math directive + - Figures + - Referencing/numbering PR + - numref/eq/ref + + - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS + + - How are we working with styles? + + - There is some copying back and forth of the .css - Damián - - Learning Myst internals working in the Nikola + Myst story - - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community - - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? + + - Learning Myst internals working in the Nikola + Myst story + - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community + - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? ## Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - NAME: ITEM (EXPECTED TIME TO DISCUSS) - + - Discuss team activity board proposal (https://github.com/executablebooks/meta/issues/441) + - The goal of this board is to coordinate and plan our major work items, to make it clear who is working on what, and to help signal boost items for review/discussion. - Is this board structure worth trying as-is or are there major changes to make to it? - If we want to try this process, perhaps we should use this meeting to add some initial items to the board? **Discussion:** + 1. This was discussed with the team and we agreed to use it this month to see how it works. -2. Any suggestions to simplify or improve the Activity Board was encouraged. -3. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. -4. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get -more distributed reviews across the team. -5. We should add the Activity Board as a standing discussion point for the monthly meeting +1. Any suggestions to simplify or improve the Activity Board was encouraged. +1. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. +1. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get + more distributed reviews across the team. +1. We should add the Activity Board as a standing discussion point for the monthly meeting - - Steve: Next Steps for Thebe - - Refactoring the one big file into more manageable chunks - - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all - - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 +- Steve: Next Steps for Thebe + - Refactoring the one big file into more manageable chunks + - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all + - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 **Discussion:** -1. This was discussed in the Reports section. + +1. This was discussed in the Reports section. ## July 1st, 2021 @@ -319,16 +338,17 @@ This is a place to make announcements (without a need for discussion), short upd - QuantEcon: 4/5 Projects running Jupyter Book (remaining: julia) - ANU Team: Working on Support for Individual Page PDF (via LaTeX) generation (Lead: @mmcky) - - Chris H notes that we should include updates about QuantEcon lectures conversion etc - - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects + - Chris H notes that we should include updates about QuantEcon lectures conversion etc + - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects #### Chris S. **Recent work** + - Released [sphinx-external-toc](https://sphinx-external-toc.readthedocs.io) and integrated in Jupyter-Book - - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) - - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees - - Integration in JB also includes addition of "pluggable" CLI + - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) + - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees + - Integration in JB also includes addition of "pluggable" CLI - Released markdown-it-py v1.0, i.e. fully stable - Released myst-parser v0.15.0, with sphinx v4 support - Should be moving all repositories to sphinx v4 @@ -341,12 +361,13 @@ This is a place to make announcements (without a need for discussion), short upd - Intend to make all plugins for parity with [mdit-py-plugins](https://github.com/executablebooks/mdit-py-plugins), and thus myst-parser extensions **Intended work** + - Update [MyST VS Code extension](https://github.com/executablebooks/myst-language-support) to use new markdown-it plugins - Plus hopefully LSP support - Look into recently finalised Notebook API: https://code.visualstudio.com/api/extension-guides/notebook - Create sphinx-design: An iteration on sphinx-panels, but with the benefit of hindsight, and to more closely follow aspects of [Materials Design](https://material.io/design) and [Material-UI](https://material-ui.com/) - - class names that do not clash with sphinx ones (i.e. container) - - easier to set principle colors and width defaults + - class names that do not clash with sphinx ones (i.e. container) + - easier to set principle colors and width defaults - Either in myst-parser or sphinx-design have nice way to generate stylised post-header banners, with e.g. author, date, read time (see https://github.com/executablebooks/MyST-Parser/issues/372) - Improvements to myst-nb (+ jupyter-cache) - Been gradually working on it, but lot of interconnected parts 😬 @@ -355,15 +376,15 @@ This is a place to make announcements (without a need for discussion), short upd - Better support for Markdown code output - Better support for "multi-level" configuration (cell level > notebook level > conf.py level) - Improve notebook execution and (maybe) drop `auto` mode in favour of `cache` - - Support for dynamic kernel names + - Support for dynamic kernel names - How to handle glue; ideally in a kernel agnostic manner, possily with the new substitution syntax - Plugin CLI in jupyter-book for notebook execution #### Steve - Would like to: - - meet the team - - hear about thoughts on Thebelab as I'm prepping to do some work there + - meet the team + - hear about thoughts on Thebelab as I'm prepping to do some work there #### Berkeley team @@ -376,23 +397,26 @@ This is a place to make announcements (without a need for discussion), short upd - [sphinx-multitoc-numbering PR](https://github.com/executablebooks/jupyter-book/pull/1326) default behaviours (Lead: @mmcky) - Workshop for Theme Specification (Prerequisites?, Preparation?, Timing?) (Lead: @mmcky) - Any new features we should be focussing on from: https://executablebooks.org/en/latest/feature-vote.html - - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) + - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) **Didn't get to the following items** + - Bug issues in Jupyter Book: any important issues to address from: https://github.com/executablebooks/jupyter-book/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug - Jupyter-book in RTD: how can we make it happen!? - - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. + - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. - Theming: I am still keen on creating a shared infrastructure (https://github.com/executablebooks/meta/issues/279) and not necessarily being directly dependent on pydata-sphinx-theme - - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme + - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme - MyST as specification: what does that mean, how to "de-couple" from sphinx? - - What roles/directives/extensions are "core"? - - How to support additional roles/directives/extensions - - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? - - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md + - What roles/directives/extensions are "core"? + - How to support additional roles/directives/extensions + - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? + - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md John S: + - Hiring casual RAs? Chris H: + - Communicating the work we're doing - blog posts, tweets, etc? @executablebooks handle? - Coordinating around deliverables, workstreams, requests for reviews, etc? diff --git a/docs/team.md b/docs/team.md index d2f3985..812cd20 100644 --- a/docs/team.md +++ b/docs/team.md @@ -4,9 +4,9 @@ The Executable Books team is a collection of scientists, scholars, and technolog around the world. We welcome participation and contribution from the community. If you'd like to join the team, please get in touch! -Below are the core `executablebooks` team members. +Below are the core `executablebooks` team members. ## Team ```{include} team_panels_code.txt -``` \ No newline at end of file +``` diff --git a/docs/team_panels_code.txt b/docs/team_panels_code.txt index 3434867..0db8cee 100644 --- a/docs/team_panels_code.txt +++ b/docs/team_panels_code.txt @@ -83,4 +83,3 @@ ```` ````` - \ No newline at end of file diff --git a/docs/tools.md b/docs/tools.md index a29e99b..f380cda 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -3,7 +3,6 @@ There are several major tools that we have developed, or are contributing to, as a part of this project. This page describes a few major components. - ## Jupyter Book Jupyter Book is an open source project for building beautiful, @@ -11,25 +10,25 @@ publication-quality books and documents from computational material. Jupyter Book has the following main features: -* **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can +- **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can write in either Jupyter markdown, or an extended flavor of markdown with publishing features. This includes support for rich syntax such as citations and cross-references, math and equations, and figures. -* **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing +- **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing you to include your code and outputs in your book. You can also write notebooks entirely in markdown to execute when you build your book. -* **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and +- **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and markdown notebooks, execute code and insert the latest outputs into your book. In addition, cache and re-use outputs to be used later. -* **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs +- **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs as you build your documentation, and insert them in-line with your content across pages. -* **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can +- **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can toggle visibility of cells, connect with an online service like Binder, and include interactive outputs from Jupyter. -* **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, +- **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, as well as PDF outputs. -* **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one +- **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one command, like so: `jupyter-book build mybook/` ```{note} @@ -48,15 +47,15 @@ and extensibility of Sphinx with the simplicity and readability of Markdown. MyST has the following main features: -* **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire +- **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire Sphinx documentation in markdown. -* **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, +- **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, allowing you to extend your document via Sphinx extensions. -* **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such +- **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such as line commenting and footnotes. -* **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended +- **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended to add new functionality and outputs for MyST. -* **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown +- **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown (such as Jupyter Notebook markdown) is natively supported by the MyST parser. ## MyST-NB @@ -66,16 +65,16 @@ MyST has the following main features: `MyST-NB` is an open source tool for working with Jupyter Notebooks in the Sphinx ecosystem. It provides the following primary features: -* **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter +- **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter Notebooks into Sphinx documents. -* **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. +- **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. Save time building your documentation without needing to commit your notebook outputs directly into `git`. -* **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown +- **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown allows you to write Sphinx roles and directives in markdown. -* **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs +- **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs as you build your documentation, and insert them across pages. -* **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can +- **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can define the structure of a notebook *in pure-text* making it more diff-able. In addition, there are several options for controlling the look and feel of how your @@ -88,16 +87,15 @@ notebooks are used in your documentation. This is a lightweight Sphinx theme designed to mimic the look-and-feel of an interactive book. It has the following primary features: -* **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** +- **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** for visual elements and functionality. -* **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, +- **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, such as [the Edward Tufte CSS guide](https://edwardtufte.github.io/tufte-css/) -* **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, +- **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, and interactive functionality are all supported. -* **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with +- **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with computational material, connect your site to an online BinderHub for interactive content. - ## Jupyter Cache ([link to documentation](https://jupyter-cache.readthedocs.io)) @@ -112,7 +110,6 @@ text documents), during which it is desired that notebooks can be auto-executed only if the notebook had been modified in a way that may alter its code cell outputs. - ## Markdown-it-py ([link to documentation](https://markdown-it-py.readthedocs.io)) @@ -129,14 +126,12 @@ Here are its main features: - High speed (see our [benchmarking tests](https://markdown-it-py.readthedocs.io/en/latest/other.html#performance)) - [Safe by default](https://markdown-it-py.readthedocs.io/en/latest/other.html#security) - - ## A collection of Sphinx extensions In addition to these major tools described above, the EBP also maintains a number of tools in the Sphinx ecosystem for writing beautiful online books and documents. For example: -* [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) -* [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) -* [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) +- [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) +- [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) +- [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) diff --git a/docs/updates/2020-02-25-hello-world.md b/docs/updates/2020-02-25-hello-world.md index 9c00689..ef0bf1e 100644 --- a/docs/updates/2020-02-25-hello-world.md +++ b/docs/updates/2020-02-25-hello-world.md @@ -48,28 +48,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -* **Support casual users equally to power users**. Complicating the feature +- **Support casual users equally to power users**. Complicating the feature space to support a "power user feature" should be done with great care. -* **Build modular components that are useful elsewhere**. Rather than building +- **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -* **Use pre-existing technology where possible**. Rather than re-inventing +- **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -* **Use pre-existing standards where possible**. In the event that we must +- **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -* **Contribute improvements upstream**. Where we utilize pre-existing tools, +- **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -* **Design for the future**. While we have a bit of funding now, it won't last +- **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -* **Users should not need to know anything about the build system**. If they +- **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, etc should not be a requirement. They should only need to use a simple tool to control the process. -* **Don't try to do everything**. Focus our tools on publishing +- **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. ## What does it mean to publish executable documents? diff --git a/docs/updates/2020-08-07-announce-book.md b/docs/updates/2020-08-07-announce-book.md index 1ee8c33..2767e1e 100644 --- a/docs/updates/2020-08-07-announce-book.md +++ b/docs/updates/2020-08-07-announce-book.md @@ -110,12 +110,12 @@ The biggest change under-the-hood is that Jupyter Book now uses [the Sphinx docu Instead of being a single repository, the old Jupyter Book repository has now been separated into several modular tools. **Each of these tools can be used on their own in your Sphinx documentation**, and they can be coordinated together *via* Jupyter Book: -* **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. -* **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. -* **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). -* **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. -* **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. -* Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). +- **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. +- **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. +- **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). +- **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. +- **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. +- Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). We'll write a more developer-focused post in the future to describe each of these components in more detail. diff --git a/docs/updates/2021-06-18-update-toc.md b/docs/updates/2021-06-18-update-toc.md index 6a5dc5f..2d9dc03 100644 --- a/docs/updates/2021-06-18-update-toc.md +++ b/docs/updates/2021-06-18-update-toc.md @@ -127,6 +127,7 @@ chapters: - file: publish/gh-pages - file: publish/netlify ``` + ::: ## Step 4: Move the configuration @@ -135,7 +136,6 @@ The new TOC structure has a more explicit configuration structure, and has diffe Because we wish for **all** sections to be numbered, we will keep `numbered: true`, but must move it to a `defaults` key, which makes it a default for all pages in the TOC. - ```yaml root: intro format: jb-book diff --git a/docs/updates/2021-06-5-release-jb-v0.11.1.md b/docs/updates/2021-06-5-release-jb-v0.11.1.md index bbfd0e4..b7e4457 100644 --- a/docs/updates/2021-06-5-release-jb-v0.11.1.md +++ b/docs/updates/2021-06-5-release-jb-v0.11.1.md @@ -13,10 +13,10 @@ We'd also like to blog about releases more often so it's easier to track major u This post is an attempt at crafting a blog post entirely made out of tweets! ``` -We're pleased to announce a new version of Jupyter Book has just been released! You can check out the CHANGELOG here: https://jupyterbook.org/reference/_changelog.html#v0-11-0 +We're pleased to announce a new version of Jupyter Book has just been released! You can check out the CHANGELOG here: https://jupyterbook.org/reference/\_changelog.html#v0-11-0 ⚠BREAKING CHANGE⚠. -The Table of Contents structure is now slightly different. It now follows a "schema" that makes the TOC easier to parse and understand. See the changelog for details: https://jupyterbook.org/reference/_changelog.html#breaking +The Table of Contents structure is now slightly different. It now follows a "schema" that makes the TOC easier to parse and understand. See the changelog for details: https://jupyterbook.org/reference/\_changelog.html#breaking In addition, there are a few nice command line options for *migrating* an old TOC to a new one, as well as creating TOCs from book structures, and vice versa. For example: https://jupyterbook.org/structure/toc-generate.html diff --git a/requirements.txt b/requirements.txt index 890aa65..63cba3e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,4 +9,4 @@ ablog # For the feature voting code ghapi pandas -tabulate \ No newline at end of file +tabulate From 925d588b02c29feb71b282064e89f8c930b9d16e Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 3 Mar 2022 17:02:07 -0800 Subject: [PATCH 2/9] revert to master --- .pre-commit-config.yaml | 4 + docs/Makefile | 2 +- docs/_static/custom.css | 2 +- docs/about.md | 26 +- docs/communication.md | 1 - docs/conf.py | 8 +- docs/feature-vote.md | 6 +- docs/gallery.yml | 2 +- docs/index.md | 2 + docs/meetings/2021.md | 378 +++++++++---------- docs/team.md | 4 +- docs/team_panels_code.txt | 1 + docs/tools.md | 53 +-- docs/updates/2020-02-25-hello-world.md | 16 +- docs/updates/2020-08-07-announce-book.md | 12 +- docs/updates/2021-06-18-update-toc.md | 2 +- docs/updates/2021-06-5-release-jb-v0.11.1.md | 4 +- requirements.txt | 2 +- 18 files changed, 255 insertions(+), 270 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2ef90b9..edeb2cd 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -25,3 +25,7 @@ repos: rev: 0.7.13 hooks: - id: mdformat + additional_dependencies: + - mdformat-gfm + - mdformat-myst + - mdformat-black diff --git a/docs/Makefile b/docs/Makefile index ef45bc1..8533f57 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,4 +20,4 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) live: - sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt + sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt \ No newline at end of file diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 0512ed1..d671601 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -9,4 +9,4 @@ ul.postlist > li > p:first-child { .landing-grid .sd-card-header { background-color: #f3772638; -} +} \ No newline at end of file diff --git a/docs/about.md b/docs/about.md index e10c50e..6c76a41 100644 --- a/docs/about.md +++ b/docs/about.md @@ -24,20 +24,20 @@ professional computational narratives (books, lecture series, articles, etc.) using open source tools. We want users in the scientific, academic, and data science communities to be able to do the following: -- **Write their content in either markdown text files, or Jupyter Notebooks**. +* **Write their content in either markdown text files, or Jupyter Notebooks**. These files include rich content - outputs from running code, references and cross-references, equations, etc. -- **Execute content and cache the results**. Intelligent caching means +* **Execute content and cache the results**. Intelligent caching means that only modified code cells are re-run. -- **Combine cached outputs with content files with a document model**. Using +* **Combine cached outputs with content files with a document model**. Using the excellent [Sphinx](https://www.sphinx-doc.org/en/master/) documentation stack, documents can include many features for publishing, such as equations, cross-references, and citations. -- **Build interactive HTML or publication-quality PDF outputs**. Sometimes +* **Build interactive HTML or publication-quality PDF outputs**. Sometimes users wish to create rich and interactive websites, other times they want to send a high-quality PDF to a publisher. This system will treat both as equal citizens. -- **Control everything above with a simple command-line interface**. Most +* **Control everything above with a simple command-line interface**. Most users should not have to know anything about Sphinx, caching, etc. A simple user interface will hide most of the complexity of this process. @@ -50,28 +50,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -- **Give equal support to casual users and power users**. Complicating the feature +* **Give equal support to casual users and power users**. Complicating the feature space to support a "power user feature" should be done with great care. -- **Build modular components that are useful elsewhere**. Rather than building +* **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -- **Use pre-existing technology where possible**. Rather than re-inventing +* **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -- **Use pre-existing standards where possible**. In the event that we must +* **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -- **Contribute improvements upstream**. Where we utilize pre-existing tools, +* **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -- **Design for the future**. While we have a bit of funding now, it won't last +* **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -- **Users should not need to know anything about the build system**. If they +* **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, and so on should not be a requirement. They should only need to use a simple tool to control the process. -- **Don't try to do everything**. Focus our tools on publishing +* **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. Browse the rest of this site for more information about what we're working diff --git a/docs/communication.md b/docs/communication.md index 8cec0e5..4c612e2 100644 --- a/docs/communication.md +++ b/docs/communication.md @@ -12,7 +12,6 @@ This is open to anybody, and is a space where people can ask questions and help Please feel free to provide support, advice, etc to anybody on this forum. (comms:issues)= - ## GitHub Issues For conversations around specific actions, tasks, features, etc, we use GitHub issues in each repository. diff --git a/docs/conf.py b/docs/conf.py index db93b7c..8b67f22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -189,10 +189,10 @@ def build_gallery(app: Sphinx): ) grid_items = "\n".join(grid_items) - # :column: text-center col-6 col-lg-4 - # :card: +my-2 - # :img-top-cls: w-75 m-auto p-2 - # :body: d-none +# :column: text-center col-6 col-lg-4 +# :card: +my-2 +# :img-top-cls: w-75 m-auto p-2 +# :body: d-none panels = f""" ``````{{grid}} 1 2 3 3 diff --git a/docs/feature-vote.md b/docs/feature-vote.md index 2bb1421..dbc1894 100644 --- a/docs/feature-vote.md +++ b/docs/feature-vote.md @@ -1,13 +1,12 @@ (feature-note)= - # Feature voting board You can help us to prioritise development of new features by leaving a [👍 reaction](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) on the first comment of any `enhancement` issue. -Below is a list of all current enhancement issues from our core repositories,\[^a\] ordered by 👍 +Below is a list of all current enhancement issues from our core repositories,[^a] ordered by 👍 Click the `+` to see more details. -\[^a\]: The data in this table is updated every day. +[^a]: The data in this table is updated every day.
@@ -17,7 +16,6 @@ Click the `+` to see more details.
- diff --git a/docs/gallery.yml b/docs/gallery.yml index 386acc0..afe44b1 100644 --- a/docs/gallery.yml +++ b/docs/gallery.yml @@ -147,7 +147,7 @@ image: https://raw.githubusercontent.com/rafneta/CienciaDatosPythonCIDE/master/docs/logo.jpg website: https://rafneta.github.io/CienciaDatosPythonCIDE/intro.html - name: "Development Data Partnership" - repository: + repository: image: https://raw.githubusercontent.com/datapartnership/welcome/master/images/logo.png website: https://docs.datapartnership.org - name: "OpenPifPaf Guide" diff --git a/docs/index.md b/docs/index.md index 6b6bdb0..4a4d019 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,6 +39,7 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co ::: :::: + ## Acknowledgements :::{image} https://pbs.twimg.com/profile_images/1226944724365447169/MzFpwY5P_400x400.png @@ -49,6 +50,7 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co The Executable Books Project is supported by several institutions and members of open source projects. In particular, many thanks to the [Sloan Foundation](https://sloan.org) which [provides support for the Executable Books Project](https://sloan.org/grant-detail/9231). + ```{toctree} :maxdepth: 2 :caption: Get Involved diff --git a/docs/meetings/2021.md b/docs/meetings/2021.md index 7a273c5..a0a0e0b 100644 --- a/docs/meetings/2021.md +++ b/docs/meetings/2021.md @@ -16,18 +16,19 @@ ### Team updates -- \[sphinx-exercise\] has been re-factored to make the extension more maintainable. - - https://github.com/executablebooks/sphinx-exercise/pull/37 - - no major user facing changes (except some style updates to output) - - focus: use sphinx internals and AST as much as possible - - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase - - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) - - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html - - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: - - custom styling - - custom options - - ref and numref integration - - autonumbering of nodes (i.e. numref) + +- [sphinx-exercise] has been re-factored to make the extension more maintainable. + - https://github.com/executablebooks/sphinx-exercise/pull/37 + - no major user facing changes (except some style updates to output) + - focus: use sphinx internals and AST as much as possible + - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase + - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) + - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html + - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: + - custom styling + - custom options + - ref and numref integration + - autonumbering of nodes (i.e. numref) - Rowan - Javascript PR merges in - Low hanging fruit is done on the JS side @@ -63,49 +64,49 @@ ### Team updates - Chris H - - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 - - Focusing most of my time trying to document things + un-block people - - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it + - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 + - Focusing most of my time trying to document things + un-block people + - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it - Steve P - - Progress on thebe: - - Major styles bug fixed - - First cut of status and activate button out - - Changed the docs & examples to use latest build - Thanks to recent RTD changes - - Started a Jupyterlite example - have JupyterLiteServer running in browser - - Next Steps: - - Test & Release - - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) - - Refactoring - - separate jquery layer from low level api (opens up more options for integration) - - document jquery and low level api - - follow through on rename - - Include Jupyterlite kernel option (and generalise) - - Tackle enhancements from Chris S. in thebe / sphinx-thebe + - Progress on thebe: + - Major styles bug fixed + - First cut of status and activate button out + - Changed the docs & examples to use latest build - Thanks to recent RTD changes + - Started a Jupyterlite example - have JupyterLiteServer running in browser + - Next Steps: + - Test & Release + - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) + - Refactoring + - separate jquery layer from low level api (opens up more options for integration) + - document jquery and low level api + - follow through on rename + - Include Jupyterlite kernel option (and generalise) + - Tackle enhancements from Chris S. in thebe / sphinx-thebe - Matt M - - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 - - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing - - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. - - General agreement that this would be useful :-) - - Added LaTeX support to sphinx-proof - - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html - - Semantic Admonitions! + - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 + - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing + - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. + - General agreement that this would be useful :-) + - Added LaTeX support to sphinx-proof + - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html + - Semantic Admonitions! - Chris S - - +1 for `sphinx-basic-ng` and merging focus of themes - - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 - - Made PoC PR to nbclient and nbformat - - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks - - But will it go stale 😬 - - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 - - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe - - Also added merging streams in myst-nb - - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 - - Working with `cpitclaudel` to add "proper" docutils support for myst-parser - - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) - - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" + - +1 for `sphinx-basic-ng` and merging focus of themes + - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 + - Made PoC PR to nbclient and nbformat + - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks + - But will it go stale 😬 + - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 + - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe + - Also added merging streams in myst-nb + - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 + - Working with `cpitclaudel` to add "proper" docutils support for myst-parser + - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) + - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" - Rowan - - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. - - Need to get back to myst in js work, next week! - - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere + - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. + - Need to get back to myst in js work, next week! + - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere ### Agenda items @@ -114,19 +115,18 @@ - switch to new GitHub project boards? Demo here: https://github.com/orgs/executablebooks/projects/9/views/1 #### Community proposal doc - - Issue for comments/discussion: https://github.com/executablebooks/meta/issues/493 - Proposal text: https://hackmd.io/@choldgraf/HkgAIHtQY - What are some major next steps? - - Investigate the major steps we'd need to take to integrate with the Jupyter community - - Sticking points? - - We'll need to demonstrate that we have a good maintainability story - - Might have questions around the different parts of EBP - - Start to get feedback in the Jupyter ecosystem - - Threads in the discourse + the governance repo - - Talk to stakeholders in that community and see if there are any things we should think about it - - Crystallize the community strategy doc into some concrete next steps - - Decide on an order of operations for things to tackle + - Investigate the major steps we'd need to take to integrate with the Jupyter community + - Sticking points? + - We'll need to demonstrate that we have a good maintainability story + - Might have questions around the different parts of EBP + - Start to get feedback in the Jupyter ecosystem + - Threads in the discourse + the governance repo + - Talk to stakeholders in that community and see if there are any things we should think about it + - Crystallize the community strategy doc into some concrete next steps + - Decide on an order of operations for things to tackle ## September 1st 2021 @@ -137,7 +137,7 @@ If you are joining the team video meeting, sign in below so we know who was here - Rowan Cockett / Curvenote / rowanc1 - Matt McKay / ANU / mmcky - Chris Holdgraf / 2i2c / choldgraf -- Damián Avila / 2i2c / damianavila +- Damián Avila / 2i2c / damianavila - Chris Sewell / EPFL / chrisjsewell ### Reports, updates, and celebrations @@ -145,61 +145,55 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - THEBE: - - - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing - - Opened(opening) tickets on activity board for dicussion - - Refactoring, improving test coverage and docs - - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection + - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing + - Opened(opening) tickets on activity board for dicussion + - Refactoring, improving test coverage and docs + - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection - Some blog post about MyST in my personal blog (Damián) - - - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) - - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) - - Eventually, a part 3 with some coding experiment/stuff + - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) + - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) + - Eventually, a part 3 with some coding experiment/stuff - Sphinx 4 Upgrade (Matt) - - - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 - - Action: Cut a new release right after merge + - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 + - Action: Cut a new release right after merge - ReadTheDocs integration (Chris S) - - - That is now working - - PR is open - just waiting on documenting it up - - Action: Needs Doc Update + - That is now working + - PR is open - just waiting on documenting it up + - Action: Needs Doc Update ### Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - Steve: Thebe directions, and future focus - - - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? - - A lot of issues in the repository - - Was a JupyterCon Sprint + a board from that - - Would like to do a bit of planning about what issues etc to tackle next - - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions - - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest + - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? + - A lot of issues in the repository + - Was a JupyterCon Sprint + a board from that + - Would like to do a bit of planning about what issues etc to tackle next + - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions + - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest - Rowan: Thoughts on how to move JS-Myst forward (dev branch?) - - - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. - - Might just be an off month?! - - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? - - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. - - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. + - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. + - Might just be an off month?! + - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? + - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. + - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. - Chris H: in-line markdown execution? + - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 + - The difficulty is in the specification + - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) + - An easy first step would be to do "read only inline markdown" + - This is a really popular feature of RMarkdown / Quarto Markdown + - Can you start with the restriction "we should be able to still run every code cell" + - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` + - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. + - You'd then do the execution, and at the end of the time that - - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 - - The difficulty is in the specification - - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) - - An easy first step would be to do "read only inline markdown" - - This is a really popular feature of RMarkdown / Quarto Markdown - - Can you start with the restriction "we should be able to still run every code cell" - - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` - - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. - - You'd then do the execution, and at the end of the time that # 05th August 2021 @@ -216,107 +210,94 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - Chris Sewell - - - Sphinx Designs - better designed panels, will come into jupyter book at some point - - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten - - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! - - There is also multi-processing on the notebooks! 💥 - - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) - - Javascript! - - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) - - There are same directives and roles from Python - - Same arguments/content - - This is now over to the vscode extension - - MyST as a "standard" - - What roles, directives, blocks to we need that are copied over in another language - - We should get the critical ones in a list somewhere! - - Forming specs in a collaborative way (Identify Good Tools for this?) - -- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) - - - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) - - Adding a directive that is a question, and then how do you add code? - - Directive at the top level and then code and exercise. - - Violates the core design of the Jupyter Notebook -- nested code cells - - Got rid of "nested" concepts - - So how do you have "Gated" directive (open/close) around a few code cells - - This is more compliant with other tools like Jupytext - - Not sure if there is a Gated directive, or prior art in the Sphinx world? - - Other options: - - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) - - Glue? (currently restricted to python, cather than cellId or something) - - Similar ideas playing with at Curvenote! (copy/paste) - - Consideration is mostly from an authorship perspective + - Sphinx Designs - better designed panels, will come into jupyter book at some point + - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten + - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! + - There is also multi-processing on the notebooks! 💥 + - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) + - Javascript! + - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) + - There are same directives and roles from Python + - Same arguments/content + - This is now over to the vscode extension + - MyST as a "standard" + - What roles, directives, blocks to we need that are copied over in another language + - We should get the critical ones in a list somewhere! + - Forming specs in a collaborative way (Identify Good Tools for this?) + +- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) + - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) + - Adding a directive that is a question, and then how do you add code? + - Directive at the top level and then code and exercise. + - Violates the core design of the Jupyter Notebook -- nested code cells + - Got rid of "nested" concepts + - So how do you have "Gated" directive (open/close) around a few code cells + - This is more compliant with other tools like Jupytext + - Not sure if there is a Gated directive, or prior art in the Sphinx world? + - Other options: + - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) + - Glue? (currently restricted to python, cather than cellId or something) + - Similar ideas playing with at Curvenote! (copy/paste) + - Consideration is mostly from an authorship perspective - Steve Purves: Thebe - - - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development - - PR for a small feature - progress indicator - - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better - - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on - - Next up: - - Connecting to many different kernals, and having some basic management on that! + - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development + - PR for a small feature - progress indicator + - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better + - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on + - Next up: + - Connecting to many different kernals, and having some basic management on that! - Rowan: MyST in JS - - - Working on myst in JS. Migrating work over to docutils and cleaning up along the way - - - Still basics of various libraries - - - 10 or so PRs up at the moment! - - - Basics: - - sub/sup/abbr - - internationalization? \[each role/directive has a different name\] - - Can generate various dicts to export - - Admonitions - - Math - - amsmath, dollar, math directive - - Figures - - Referencing/numbering PR - - numref/eq/ref - - - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS - - - How are we working with styles? - - - There is some copying back and forth of the .css + - Working on myst in JS. Migrating work over to docutils and cleaning up along the way + - Still basics of various libraries + + - 10 or so PRs up at the moment! + - Basics: + - sub/sup/abbr + - internationalization? [each role/directive has a different name] + - Can generate various dicts to export + - Admonitions + - Math + - amsmath, dollar, math directive + - Figures + - Referencing/numbering PR + - numref/eq/ref + - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS + - How are we working with styles? + - There is some copying back and forth of the .css - Damián - - - Learning Myst internals working in the Nikola + Myst story - - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community - - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? + - Learning Myst internals working in the Nikola + Myst story + - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community + - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? ## Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - NAME: ITEM (EXPECTED TIME TO DISCUSS) - + - Discuss team activity board proposal (https://github.com/executablebooks/meta/issues/441) - - The goal of this board is to coordinate and plan our major work items, to make it clear who is working on what, and to help signal boost items for review/discussion. - Is this board structure worth trying as-is or are there major changes to make to it? - If we want to try this process, perhaps we should use this meeting to add some initial items to the board? **Discussion:** - 1. This was discussed with the team and we agreed to use it this month to see how it works. -1. Any suggestions to simplify or improve the Activity Board was encouraged. -1. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. -1. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get - more distributed reviews across the team. -1. We should add the Activity Board as a standing discussion point for the monthly meeting +2. Any suggestions to simplify or improve the Activity Board was encouraged. +3. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. +4. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get +more distributed reviews across the team. +5. We should add the Activity Board as a standing discussion point for the monthly meeting -- Steve: Next Steps for Thebe - - Refactoring the one big file into more manageable chunks - - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all - - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 + - Steve: Next Steps for Thebe + - Refactoring the one big file into more manageable chunks + - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all + - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 **Discussion:** - -1. This was discussed in the Reports section. +1. This was discussed in the Reports section. ## July 1st, 2021 @@ -338,17 +319,16 @@ This is a place to make announcements (without a need for discussion), short upd - QuantEcon: 4/5 Projects running Jupyter Book (remaining: julia) - ANU Team: Working on Support for Individual Page PDF (via LaTeX) generation (Lead: @mmcky) - - Chris H notes that we should include updates about QuantEcon lectures conversion etc - - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects + - Chris H notes that we should include updates about QuantEcon lectures conversion etc + - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects #### Chris S. **Recent work** - - Released [sphinx-external-toc](https://sphinx-external-toc.readthedocs.io) and integrated in Jupyter-Book - - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) - - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees - - Integration in JB also includes addition of "pluggable" CLI + - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) + - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees + - Integration in JB also includes addition of "pluggable" CLI - Released markdown-it-py v1.0, i.e. fully stable - Released myst-parser v0.15.0, with sphinx v4 support - Should be moving all repositories to sphinx v4 @@ -361,13 +341,12 @@ This is a place to make announcements (without a need for discussion), short upd - Intend to make all plugins for parity with [mdit-py-plugins](https://github.com/executablebooks/mdit-py-plugins), and thus myst-parser extensions **Intended work** - - Update [MyST VS Code extension](https://github.com/executablebooks/myst-language-support) to use new markdown-it plugins - Plus hopefully LSP support - Look into recently finalised Notebook API: https://code.visualstudio.com/api/extension-guides/notebook - Create sphinx-design: An iteration on sphinx-panels, but with the benefit of hindsight, and to more closely follow aspects of [Materials Design](https://material.io/design) and [Material-UI](https://material-ui.com/) - - class names that do not clash with sphinx ones (i.e. container) - - easier to set principle colors and width defaults + - class names that do not clash with sphinx ones (i.e. container) + - easier to set principle colors and width defaults - Either in myst-parser or sphinx-design have nice way to generate stylised post-header banners, with e.g. author, date, read time (see https://github.com/executablebooks/MyST-Parser/issues/372) - Improvements to myst-nb (+ jupyter-cache) - Been gradually working on it, but lot of interconnected parts 😬 @@ -376,15 +355,15 @@ This is a place to make announcements (without a need for discussion), short upd - Better support for Markdown code output - Better support for "multi-level" configuration (cell level > notebook level > conf.py level) - Improve notebook execution and (maybe) drop `auto` mode in favour of `cache` - - Support for dynamic kernel names + - Support for dynamic kernel names - How to handle glue; ideally in a kernel agnostic manner, possily with the new substitution syntax - Plugin CLI in jupyter-book for notebook execution #### Steve - Would like to: - - meet the team - - hear about thoughts on Thebelab as I'm prepping to do some work there + - meet the team + - hear about thoughts on Thebelab as I'm prepping to do some work there #### Berkeley team @@ -397,26 +376,23 @@ This is a place to make announcements (without a need for discussion), short upd - [sphinx-multitoc-numbering PR](https://github.com/executablebooks/jupyter-book/pull/1326) default behaviours (Lead: @mmcky) - Workshop for Theme Specification (Prerequisites?, Preparation?, Timing?) (Lead: @mmcky) - Any new features we should be focussing on from: https://executablebooks.org/en/latest/feature-vote.html - - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) + - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) **Didn't get to the following items** - - Bug issues in Jupyter Book: any important issues to address from: https://github.com/executablebooks/jupyter-book/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug - Jupyter-book in RTD: how can we make it happen!? - - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. + - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. - Theming: I am still keen on creating a shared infrastructure (https://github.com/executablebooks/meta/issues/279) and not necessarily being directly dependent on pydata-sphinx-theme - - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme + - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme - MyST as specification: what does that mean, how to "de-couple" from sphinx? - - What roles/directives/extensions are "core"? - - How to support additional roles/directives/extensions - - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? - - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md + - What roles/directives/extensions are "core"? + - How to support additional roles/directives/extensions + - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? + - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md John S: - - Hiring casual RAs? Chris H: - - Communicating the work we're doing - blog posts, tweets, etc? @executablebooks handle? - Coordinating around deliverables, workstreams, requests for reviews, etc? diff --git a/docs/team.md b/docs/team.md index 812cd20..d2f3985 100644 --- a/docs/team.md +++ b/docs/team.md @@ -4,9 +4,9 @@ The Executable Books team is a collection of scientists, scholars, and technolog around the world. We welcome participation and contribution from the community. If you'd like to join the team, please get in touch! -Below are the core `executablebooks` team members. +Below are the core `executablebooks` team members. ## Team ```{include} team_panels_code.txt -``` +``` \ No newline at end of file diff --git a/docs/team_panels_code.txt b/docs/team_panels_code.txt index 0db8cee..3434867 100644 --- a/docs/team_panels_code.txt +++ b/docs/team_panels_code.txt @@ -83,3 +83,4 @@ ```` ````` + \ No newline at end of file diff --git a/docs/tools.md b/docs/tools.md index f380cda..a29e99b 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -3,6 +3,7 @@ There are several major tools that we have developed, or are contributing to, as a part of this project. This page describes a few major components. + ## Jupyter Book Jupyter Book is an open source project for building beautiful, @@ -10,25 +11,25 @@ publication-quality books and documents from computational material. Jupyter Book has the following main features: -- **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can +* **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can write in either Jupyter markdown, or an extended flavor of markdown with publishing features. This includes support for rich syntax such as citations and cross-references, math and equations, and figures. -- **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing +* **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing you to include your code and outputs in your book. You can also write notebooks entirely in markdown to execute when you build your book. -- **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and +* **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and markdown notebooks, execute code and insert the latest outputs into your book. In addition, cache and re-use outputs to be used later. -- **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs +* **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs as you build your documentation, and insert them in-line with your content across pages. -- **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can +* **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can toggle visibility of cells, connect with an online service like Binder, and include interactive outputs from Jupyter. -- **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, +* **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, as well as PDF outputs. -- **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one +* **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one command, like so: `jupyter-book build mybook/` ```{note} @@ -47,15 +48,15 @@ and extensibility of Sphinx with the simplicity and readability of Markdown. MyST has the following main features: -- **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire +* **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire Sphinx documentation in markdown. -- **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, +* **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, allowing you to extend your document via Sphinx extensions. -- **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such +* **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such as line commenting and footnotes. -- **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended +* **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended to add new functionality and outputs for MyST. -- **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown +* **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown (such as Jupyter Notebook markdown) is natively supported by the MyST parser. ## MyST-NB @@ -65,16 +66,16 @@ MyST has the following main features: `MyST-NB` is an open source tool for working with Jupyter Notebooks in the Sphinx ecosystem. It provides the following primary features: -- **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter +* **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter Notebooks into Sphinx documents. -- **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. +* **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. Save time building your documentation without needing to commit your notebook outputs directly into `git`. -- **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown +* **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown allows you to write Sphinx roles and directives in markdown. -- **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs +* **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs as you build your documentation, and insert them across pages. -- **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can +* **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can define the structure of a notebook *in pure-text* making it more diff-able. In addition, there are several options for controlling the look and feel of how your @@ -87,15 +88,16 @@ notebooks are used in your documentation. This is a lightweight Sphinx theme designed to mimic the look-and-feel of an interactive book. It has the following primary features: -- **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** +* **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** for visual elements and functionality. -- **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, +* **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, such as [the Edward Tufte CSS guide](https://edwardtufte.github.io/tufte-css/) -- **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, +* **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, and interactive functionality are all supported. -- **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with +* **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with computational material, connect your site to an online BinderHub for interactive content. + ## Jupyter Cache ([link to documentation](https://jupyter-cache.readthedocs.io)) @@ -110,6 +112,7 @@ text documents), during which it is desired that notebooks can be auto-executed only if the notebook had been modified in a way that may alter its code cell outputs. + ## Markdown-it-py ([link to documentation](https://markdown-it-py.readthedocs.io)) @@ -126,12 +129,14 @@ Here are its main features: - High speed (see our [benchmarking tests](https://markdown-it-py.readthedocs.io/en/latest/other.html#performance)) - [Safe by default](https://markdown-it-py.readthedocs.io/en/latest/other.html#security) + + ## A collection of Sphinx extensions In addition to these major tools described above, the EBP also maintains a number of tools in the Sphinx ecosystem for writing beautiful online books and documents. For example: -- [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) -- [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) -- [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) +* [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) +* [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) +* [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) diff --git a/docs/updates/2020-02-25-hello-world.md b/docs/updates/2020-02-25-hello-world.md index ef0bf1e..9c00689 100644 --- a/docs/updates/2020-02-25-hello-world.md +++ b/docs/updates/2020-02-25-hello-world.md @@ -48,28 +48,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -- **Support casual users equally to power users**. Complicating the feature +* **Support casual users equally to power users**. Complicating the feature space to support a "power user feature" should be done with great care. -- **Build modular components that are useful elsewhere**. Rather than building +* **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -- **Use pre-existing technology where possible**. Rather than re-inventing +* **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -- **Use pre-existing standards where possible**. In the event that we must +* **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -- **Contribute improvements upstream**. Where we utilize pre-existing tools, +* **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -- **Design for the future**. While we have a bit of funding now, it won't last +* **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -- **Users should not need to know anything about the build system**. If they +* **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, etc should not be a requirement. They should only need to use a simple tool to control the process. -- **Don't try to do everything**. Focus our tools on publishing +* **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. ## What does it mean to publish executable documents? diff --git a/docs/updates/2020-08-07-announce-book.md b/docs/updates/2020-08-07-announce-book.md index 2767e1e..1ee8c33 100644 --- a/docs/updates/2020-08-07-announce-book.md +++ b/docs/updates/2020-08-07-announce-book.md @@ -110,12 +110,12 @@ The biggest change under-the-hood is that Jupyter Book now uses [the Sphinx docu Instead of being a single repository, the old Jupyter Book repository has now been separated into several modular tools. **Each of these tools can be used on their own in your Sphinx documentation**, and they can be coordinated together *via* Jupyter Book: -- **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. -- **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. -- **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). -- **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. -- **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. -- Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). +* **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. +* **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. +* **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). +* **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. +* **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. +* Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). We'll write a more developer-focused post in the future to describe each of these components in more detail. diff --git a/docs/updates/2021-06-18-update-toc.md b/docs/updates/2021-06-18-update-toc.md index 2d9dc03..6a5dc5f 100644 --- a/docs/updates/2021-06-18-update-toc.md +++ b/docs/updates/2021-06-18-update-toc.md @@ -127,7 +127,6 @@ chapters: - file: publish/gh-pages - file: publish/netlify ``` - ::: ## Step 4: Move the configuration @@ -136,6 +135,7 @@ The new TOC structure has a more explicit configuration structure, and has diffe Because we wish for **all** sections to be numbered, we will keep `numbered: true`, but must move it to a `defaults` key, which makes it a default for all pages in the TOC. + ```yaml root: intro format: jb-book diff --git a/docs/updates/2021-06-5-release-jb-v0.11.1.md b/docs/updates/2021-06-5-release-jb-v0.11.1.md index b7e4457..bbfd0e4 100644 --- a/docs/updates/2021-06-5-release-jb-v0.11.1.md +++ b/docs/updates/2021-06-5-release-jb-v0.11.1.md @@ -13,10 +13,10 @@ We'd also like to blog about releases more often so it's easier to track major u This post is an attempt at crafting a blog post entirely made out of tweets! ``` -We're pleased to announce a new version of Jupyter Book has just been released! You can check out the CHANGELOG here: https://jupyterbook.org/reference/\_changelog.html#v0-11-0 +We're pleased to announce a new version of Jupyter Book has just been released! You can check out the CHANGELOG here: https://jupyterbook.org/reference/_changelog.html#v0-11-0 ⚠BREAKING CHANGE⚠. -The Table of Contents structure is now slightly different. It now follows a "schema" that makes the TOC easier to parse and understand. See the changelog for details: https://jupyterbook.org/reference/\_changelog.html#breaking +The Table of Contents structure is now slightly different. It now follows a "schema" that makes the TOC easier to parse and understand. See the changelog for details: https://jupyterbook.org/reference/_changelog.html#breaking In addition, there are a few nice command line options for *migrating* an old TOC to a new one, as well as creating TOCs from book structures, and vice versa. For example: https://jupyterbook.org/structure/toc-generate.html diff --git a/requirements.txt b/requirements.txt index 63cba3e..890aa65 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,4 +9,4 @@ ablog # For the feature voting code ghapi pandas -tabulate +tabulate \ No newline at end of file From f81ebee01d08bec583ec3fa07d6b884adcce81a8 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 3 Mar 2022 17:05:16 -0800 Subject: [PATCH 3/9] Update pre-commit hook --- .pre-commit-config.yaml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index edeb2cd..50de92c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -25,7 +25,8 @@ repos: rev: 0.7.13 hooks: - id: mdformat - additional_dependencies: - - mdformat-gfm - - mdformat-myst - - mdformat-black + files: docs/* + additional_dependencies: + - mdformat-gfm + - mdformat-myst + - mdformat-black From 0e68c858d53f69be44509e83baf4eb16504baad7 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 3 Mar 2022 17:06:47 -0800 Subject: [PATCH 4/9] Use mdformat plugins --- docs/Makefile | 2 +- docs/_static/custom.css | 2 +- docs/about.md | 26 +- docs/communication.md | 2 + docs/conf.py | 8 +- docs/developer.md | 1 + docs/feature-vote.md | 6 +- docs/gallery.yml | 2 +- docs/index.md | 36 +- docs/meetings/2021.md | 378 ++++++++++--------- docs/meetings/2022.md | 2 +- docs/meetings/index.md | 4 +- docs/team.md | 4 +- docs/team_panels_code.txt | 1 - docs/tools.md | 53 ++- docs/updates/2020-02-25-hello-world.md | 20 +- docs/updates/2020-08-07-announce-book.md | 20 +- docs/updates/2021-06-18-update-toc.md | 14 +- docs/updates/2021-06-5-release-jb-v0.11.1.md | 12 +- docs/updates/2021-12-18-agu-2021.md | 4 +- requirements.txt | 2 +- 21 files changed, 320 insertions(+), 279 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 8533f57..ef45bc1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,4 +20,4 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) live: - sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt \ No newline at end of file + sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt diff --git a/docs/_static/custom.css b/docs/_static/custom.css index d671601..0512ed1 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -9,4 +9,4 @@ ul.postlist > li > p:first-child { .landing-grid .sd-card-header { background-color: #f3772638; -} \ No newline at end of file +} diff --git a/docs/about.md b/docs/about.md index 6c76a41..e10c50e 100644 --- a/docs/about.md +++ b/docs/about.md @@ -24,20 +24,20 @@ professional computational narratives (books, lecture series, articles, etc.) using open source tools. We want users in the scientific, academic, and data science communities to be able to do the following: -* **Write their content in either markdown text files, or Jupyter Notebooks**. +- **Write their content in either markdown text files, or Jupyter Notebooks**. These files include rich content - outputs from running code, references and cross-references, equations, etc. -* **Execute content and cache the results**. Intelligent caching means +- **Execute content and cache the results**. Intelligent caching means that only modified code cells are re-run. -* **Combine cached outputs with content files with a document model**. Using +- **Combine cached outputs with content files with a document model**. Using the excellent [Sphinx](https://www.sphinx-doc.org/en/master/) documentation stack, documents can include many features for publishing, such as equations, cross-references, and citations. -* **Build interactive HTML or publication-quality PDF outputs**. Sometimes +- **Build interactive HTML or publication-quality PDF outputs**. Sometimes users wish to create rich and interactive websites, other times they want to send a high-quality PDF to a publisher. This system will treat both as equal citizens. -* **Control everything above with a simple command-line interface**. Most +- **Control everything above with a simple command-line interface**. Most users should not have to know anything about Sphinx, caching, etc. A simple user interface will hide most of the complexity of this process. @@ -50,28 +50,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -* **Give equal support to casual users and power users**. Complicating the feature +- **Give equal support to casual users and power users**. Complicating the feature space to support a "power user feature" should be done with great care. -* **Build modular components that are useful elsewhere**. Rather than building +- **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -* **Use pre-existing technology where possible**. Rather than re-inventing +- **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -* **Use pre-existing standards where possible**. In the event that we must +- **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -* **Contribute improvements upstream**. Where we utilize pre-existing tools, +- **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -* **Design for the future**. While we have a bit of funding now, it won't last +- **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -* **Users should not need to know anything about the build system**. If they +- **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, and so on should not be a requirement. They should only need to use a simple tool to control the process. -* **Don't try to do everything**. Focus our tools on publishing +- **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. Browse the rest of this site for more information about what we're working diff --git a/docs/communication.md b/docs/communication.md index 4c612e2..ef3dece 100644 --- a/docs/communication.md +++ b/docs/communication.md @@ -12,6 +12,7 @@ This is open to anybody, and is a space where people can ask questions and help Please feel free to provide support, advice, etc to anybody on this forum. (comms:issues)= + ## GitHub Issues For conversations around specific actions, tasks, features, etc, we use GitHub issues in each repository. @@ -25,6 +26,7 @@ If you'd like access, please reach out to a core team member to discuss! ## Email % ref: https://github.com/executablebooks/meta/discussions/412 to share password/access + We have an e-mail address at `executablebooks@gmail.com`. All core team members should have access to this email, though it is not currently actively monitored by the team. diff --git a/docs/conf.py b/docs/conf.py index 8b67f22..db93b7c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -189,10 +189,10 @@ def build_gallery(app: Sphinx): ) grid_items = "\n".join(grid_items) -# :column: text-center col-6 col-lg-4 -# :card: +my-2 -# :img-top-cls: w-75 m-auto p-2 -# :body: d-none + # :column: text-center col-6 col-lg-4 + # :card: +my-2 + # :img-top-cls: w-75 m-auto p-2 + # :body: d-none panels = f""" ``````{{grid}} 1 2 3 3 diff --git a/docs/developer.md b/docs/developer.md index 83b513a..b5e7e14 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -26,6 +26,7 @@ doctree in `python`: ```python import pickle + doc = pickle.load(open("_build/.doctrees/", "rb")) ``` diff --git a/docs/feature-vote.md b/docs/feature-vote.md index dbc1894..d9a40f3 100644 --- a/docs/feature-vote.md +++ b/docs/feature-vote.md @@ -1,4 +1,5 @@ (feature-note)= + # Feature voting board You can help us to prioritise development of new features by leaving a [👍 reaction](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) on the first comment of any `enhancement` issue. @@ -6,8 +7,6 @@ You can help us to prioritise development of new features by leaving a [👍 rea Below is a list of all current enhancement issues from our core repositories,[^a] ordered by 👍 Click the `+` to see more details. -[^a]: The data in this table is updated every day. -
```{include} issue-votes.txt @@ -16,6 +15,7 @@ Click the `+` to see more details.
+ @@ -27,3 +27,5 @@ $(document).ready( function () { }); } ); + +[^a]: The data in this table is updated every day. diff --git a/docs/gallery.yml b/docs/gallery.yml index afe44b1..386acc0 100644 --- a/docs/gallery.yml +++ b/docs/gallery.yml @@ -147,7 +147,7 @@ image: https://raw.githubusercontent.com/rafneta/CienciaDatosPythonCIDE/master/docs/logo.jpg website: https://rafneta.github.io/CienciaDatosPythonCIDE/intro.html - name: "Development Data Partnership" - repository: + repository: image: https://raw.githubusercontent.com/datapartnership/welcome/master/images/logo.png website: https://docs.datapartnership.org - name: "OpenPifPaf Guide" diff --git a/docs/index.md b/docs/index.md index 4a4d019..d53ad26 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,31 +7,31 @@ computational narratives using the Jupyter ecosystem. We are the community behind [Jupyter Book](https://jupyterbook.org)--an open source project for building beautiful, publication-quality books and documents from computational material--as well as [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/)--a rich and extensible flavor of Markdown meant for technical documentation and publishing. -::::{grid} 1 2 2 2 +::::\{grid} 1 2 2 2 :class-container: landing-grid -:::{grid-item-card} +:::\{grid-item-card} :padding: 2 For contributors 👩‍💻 ^^^ Read our [Contributing Guide](contributing.md) to learn about the conventions we follow, and see [our community forum](https://github.com/executablebooks/meta/discussions) to ask questions and help others. ::: -:::{grid-item-card} +:::\{grid-item-card} :padding: 2 Be inspired ✨ ^^^ Our [Gallery of Jupyter Books](gallery.md) has contributions from across the community, and [our blog](updates.md) has updates from the community. ::: -:::{grid-item-card} +:::\{grid-item-card} :padding: 2 Tools we build 👍 ^^^ Our [Feature Voting board](feature-vote.md) is an easy way for community members to voice support for features and enhancements. Our [Tools Page](tools.md) also lists many of the tools we build to learn more. ::: -:::{grid-item-card} +:::\{grid-item-card} :padding: 2 About the project ℹ️ ^^^ @@ -39,10 +39,9 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co ::: :::: - ## Acknowledgements -:::{image} https://pbs.twimg.com/profile_images/1226944724365447169/MzFpwY5P_400x400.png +:::\{image} https://pbs.twimg.com/profile_images/1226944724365447169/MzFpwY5P_400x400.png :class: float-left mr-2 rounded :width: 100px ::: @@ -50,11 +49,12 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co The Executable Books Project is supported by several institutions and members of open source projects. In particular, many thanks to the [Sloan Foundation](https://sloan.org) which [provides support for the Executable Books Project](https://sloan.org/grant-detail/9231). - ```{toctree} -:maxdepth: 2 -:caption: Get Involved -:hidden: +--- +maxdepth: 2 +caption: Get Involved +hidden: +--- contributing.md developer.md resources.md @@ -63,17 +63,21 @@ meetings/index.md ``` ```{toctree} -:hidden: -:caption: Our Projects and Tools +--- +hidden: +caption: Our Projects and Tools +--- feature-vote.md gallery.md tools.md ``` ```{toctree} -:maxdepth: 2 -:caption: About the Project -:hidden: +--- +maxdepth: 2 +caption: About the Project +hidden: +--- about.md team.md updates.md diff --git a/docs/meetings/2021.md b/docs/meetings/2021.md index a0a0e0b..7a273c5 100644 --- a/docs/meetings/2021.md +++ b/docs/meetings/2021.md @@ -16,19 +16,18 @@ ### Team updates - -- [sphinx-exercise] has been re-factored to make the extension more maintainable. - - https://github.com/executablebooks/sphinx-exercise/pull/37 - - no major user facing changes (except some style updates to output) - - focus: use sphinx internals and AST as much as possible - - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase - - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) - - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html - - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: - - custom styling - - custom options - - ref and numref integration - - autonumbering of nodes (i.e. numref) +- \[sphinx-exercise\] has been re-factored to make the extension more maintainable. + - https://github.com/executablebooks/sphinx-exercise/pull/37 + - no major user facing changes (except some style updates to output) + - focus: use sphinx internals and AST as much as possible + - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase + - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) + - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html + - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: + - custom styling + - custom options + - ref and numref integration + - autonumbering of nodes (i.e. numref) - Rowan - Javascript PR merges in - Low hanging fruit is done on the JS side @@ -64,49 +63,49 @@ ### Team updates - Chris H - - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 - - Focusing most of my time trying to document things + un-block people - - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it + - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 + - Focusing most of my time trying to document things + un-block people + - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it - Steve P - - Progress on thebe: - - Major styles bug fixed - - First cut of status and activate button out - - Changed the docs & examples to use latest build - Thanks to recent RTD changes - - Started a Jupyterlite example - have JupyterLiteServer running in browser - - Next Steps: - - Test & Release - - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) - - Refactoring - - separate jquery layer from low level api (opens up more options for integration) - - document jquery and low level api - - follow through on rename - - Include Jupyterlite kernel option (and generalise) - - Tackle enhancements from Chris S. in thebe / sphinx-thebe + - Progress on thebe: + - Major styles bug fixed + - First cut of status and activate button out + - Changed the docs & examples to use latest build - Thanks to recent RTD changes + - Started a Jupyterlite example - have JupyterLiteServer running in browser + - Next Steps: + - Test & Release + - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) + - Refactoring + - separate jquery layer from low level api (opens up more options for integration) + - document jquery and low level api + - follow through on rename + - Include Jupyterlite kernel option (and generalise) + - Tackle enhancements from Chris S. in thebe / sphinx-thebe - Matt M - - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 - - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing - - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. - - General agreement that this would be useful :-) - - Added LaTeX support to sphinx-proof - - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html - - Semantic Admonitions! + - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 + - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing + - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. + - General agreement that this would be useful :-) + - Added LaTeX support to sphinx-proof + - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html + - Semantic Admonitions! - Chris S - - +1 for `sphinx-basic-ng` and merging focus of themes - - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 - - Made PoC PR to nbclient and nbformat - - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks - - But will it go stale 😬 - - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 - - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe - - Also added merging streams in myst-nb - - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 - - Working with `cpitclaudel` to add "proper" docutils support for myst-parser - - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) - - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" + - +1 for `sphinx-basic-ng` and merging focus of themes + - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 + - Made PoC PR to nbclient and nbformat + - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks + - But will it go stale 😬 + - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 + - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe + - Also added merging streams in myst-nb + - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 + - Working with `cpitclaudel` to add "proper" docutils support for myst-parser + - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) + - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" - Rowan - - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. - - Need to get back to myst in js work, next week! - - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere + - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. + - Need to get back to myst in js work, next week! + - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere ### Agenda items @@ -115,18 +114,19 @@ - switch to new GitHub project boards? Demo here: https://github.com/orgs/executablebooks/projects/9/views/1 #### Community proposal doc + - Issue for comments/discussion: https://github.com/executablebooks/meta/issues/493 - Proposal text: https://hackmd.io/@choldgraf/HkgAIHtQY - What are some major next steps? - - Investigate the major steps we'd need to take to integrate with the Jupyter community - - Sticking points? - - We'll need to demonstrate that we have a good maintainability story - - Might have questions around the different parts of EBP - - Start to get feedback in the Jupyter ecosystem - - Threads in the discourse + the governance repo - - Talk to stakeholders in that community and see if there are any things we should think about it - - Crystallize the community strategy doc into some concrete next steps - - Decide on an order of operations for things to tackle + - Investigate the major steps we'd need to take to integrate with the Jupyter community + - Sticking points? + - We'll need to demonstrate that we have a good maintainability story + - Might have questions around the different parts of EBP + - Start to get feedback in the Jupyter ecosystem + - Threads in the discourse + the governance repo + - Talk to stakeholders in that community and see if there are any things we should think about it + - Crystallize the community strategy doc into some concrete next steps + - Decide on an order of operations for things to tackle ## September 1st 2021 @@ -137,7 +137,7 @@ If you are joining the team video meeting, sign in below so we know who was here - Rowan Cockett / Curvenote / rowanc1 - Matt McKay / ANU / mmcky - Chris Holdgraf / 2i2c / choldgraf -- Damián Avila / 2i2c / damianavila +- Damián Avila / 2i2c / damianavila - Chris Sewell / EPFL / chrisjsewell ### Reports, updates, and celebrations @@ -145,55 +145,61 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - THEBE: - - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing - - Opened(opening) tickets on activity board for dicussion - - Refactoring, improving test coverage and docs - - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection + + - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing + - Opened(opening) tickets on activity board for dicussion + - Refactoring, improving test coverage and docs + - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection - Some blog post about MyST in my personal blog (Damián) - - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) - - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) - - Eventually, a part 3 with some coding experiment/stuff + + - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) + - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) + - Eventually, a part 3 with some coding experiment/stuff - Sphinx 4 Upgrade (Matt) - - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 - - Action: Cut a new release right after merge + + - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 + - Action: Cut a new release right after merge - ReadTheDocs integration (Chris S) - - That is now working - - PR is open - just waiting on documenting it up - - Action: Needs Doc Update + + - That is now working + - PR is open - just waiting on documenting it up + - Action: Needs Doc Update ### Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - Steve: Thebe directions, and future focus - - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? - - A lot of issues in the repository - - Was a JupyterCon Sprint + a board from that - - Would like to do a bit of planning about what issues etc to tackle next - - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions - - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest + + - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? + - A lot of issues in the repository + - Was a JupyterCon Sprint + a board from that + - Would like to do a bit of planning about what issues etc to tackle next + - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions + - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest - Rowan: Thoughts on how to move JS-Myst forward (dev branch?) - - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. - - Might just be an off month?! - - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? - - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. - - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. + + - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. + - Might just be an off month?! + - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? + - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. + - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. - Chris H: in-line markdown execution? - - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 - - The difficulty is in the specification - - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) - - An easy first step would be to do "read only inline markdown" - - This is a really popular feature of RMarkdown / Quarto Markdown - - Can you start with the restriction "we should be able to still run every code cell" - - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` - - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. - - You'd then do the execution, and at the end of the time that + - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 + - The difficulty is in the specification + - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) + - An easy first step would be to do "read only inline markdown" + - This is a really popular feature of RMarkdown / Quarto Markdown + - Can you start with the restriction "we should be able to still run every code cell" + - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` + - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. + - You'd then do the execution, and at the end of the time that # 05th August 2021 @@ -210,94 +216,107 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - Chris Sewell - - Sphinx Designs - better designed panels, will come into jupyter book at some point - - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten - - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! - - There is also multi-processing on the notebooks! 💥 - - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) - - Javascript! - - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) - - There are same directives and roles from Python - - Same arguments/content - - This is now over to the vscode extension - - MyST as a "standard" - - What roles, directives, blocks to we need that are copied over in another language - - We should get the critical ones in a list somewhere! - - Forming specs in a collaborative way (Identify Good Tools for this?) - -- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) - - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) - - Adding a directive that is a question, and then how do you add code? - - Directive at the top level and then code and exercise. - - Violates the core design of the Jupyter Notebook -- nested code cells - - Got rid of "nested" concepts - - So how do you have "Gated" directive (open/close) around a few code cells - - This is more compliant with other tools like Jupytext - - Not sure if there is a Gated directive, or prior art in the Sphinx world? - - Other options: - - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) - - Glue? (currently restricted to python, cather than cellId or something) - - Similar ideas playing with at Curvenote! (copy/paste) - - Consideration is mostly from an authorship perspective + + - Sphinx Designs - better designed panels, will come into jupyter book at some point + - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten + - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! + - There is also multi-processing on the notebooks! 💥 + - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) + - Javascript! + - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) + - There are same directives and roles from Python + - Same arguments/content + - This is now over to the vscode extension + - MyST as a "standard" + - What roles, directives, blocks to we need that are copied over in another language + - We should get the critical ones in a list somewhere! + - Forming specs in a collaborative way (Identify Good Tools for this?) + +- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) + + - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) + - Adding a directive that is a question, and then how do you add code? + - Directive at the top level and then code and exercise. + - Violates the core design of the Jupyter Notebook -- nested code cells + - Got rid of "nested" concepts + - So how do you have "Gated" directive (open/close) around a few code cells + - This is more compliant with other tools like Jupytext + - Not sure if there is a Gated directive, or prior art in the Sphinx world? + - Other options: + - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) + - Glue? (currently restricted to python, cather than cellId or something) + - Similar ideas playing with at Curvenote! (copy/paste) + - Consideration is mostly from an authorship perspective - Steve Purves: Thebe - - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development - - PR for a small feature - progress indicator - - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better - - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on - - Next up: - - Connecting to many different kernals, and having some basic management on that! + + - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development + - PR for a small feature - progress indicator + - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better + - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on + - Next up: + - Connecting to many different kernals, and having some basic management on that! - Rowan: MyST in JS - - Working on myst in JS. Migrating work over to docutils and cleaning up along the way - - Still basics of various libraries - - - 10 or so PRs up at the moment! - - Basics: - - sub/sup/abbr - - internationalization? [each role/directive has a different name] - - Can generate various dicts to export - - Admonitions - - Math - - amsmath, dollar, math directive - - Figures - - Referencing/numbering PR - - numref/eq/ref - - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS - - How are we working with styles? - - There is some copying back and forth of the .css + + - Working on myst in JS. Migrating work over to docutils and cleaning up along the way + + - Still basics of various libraries + + - 10 or so PRs up at the moment! + + - Basics: + - sub/sup/abbr + - internationalization? \[each role/directive has a different name\] + - Can generate various dicts to export + - Admonitions + - Math + - amsmath, dollar, math directive + - Figures + - Referencing/numbering PR + - numref/eq/ref + + - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS + + - How are we working with styles? + + - There is some copying back and forth of the .css - Damián - - Learning Myst internals working in the Nikola + Myst story - - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community - - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? + + - Learning Myst internals working in the Nikola + Myst story + - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community + - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? ## Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - NAME: ITEM (EXPECTED TIME TO DISCUSS) - + - Discuss team activity board proposal (https://github.com/executablebooks/meta/issues/441) + - The goal of this board is to coordinate and plan our major work items, to make it clear who is working on what, and to help signal boost items for review/discussion. - Is this board structure worth trying as-is or are there major changes to make to it? - If we want to try this process, perhaps we should use this meeting to add some initial items to the board? **Discussion:** + 1. This was discussed with the team and we agreed to use it this month to see how it works. -2. Any suggestions to simplify or improve the Activity Board was encouraged. -3. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. -4. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get -more distributed reviews across the team. -5. We should add the Activity Board as a standing discussion point for the monthly meeting +1. Any suggestions to simplify or improve the Activity Board was encouraged. +1. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. +1. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get + more distributed reviews across the team. +1. We should add the Activity Board as a standing discussion point for the monthly meeting - - Steve: Next Steps for Thebe - - Refactoring the one big file into more manageable chunks - - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all - - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 +- Steve: Next Steps for Thebe + - Refactoring the one big file into more manageable chunks + - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all + - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 **Discussion:** -1. This was discussed in the Reports section. + +1. This was discussed in the Reports section. ## July 1st, 2021 @@ -319,16 +338,17 @@ This is a place to make announcements (without a need for discussion), short upd - QuantEcon: 4/5 Projects running Jupyter Book (remaining: julia) - ANU Team: Working on Support for Individual Page PDF (via LaTeX) generation (Lead: @mmcky) - - Chris H notes that we should include updates about QuantEcon lectures conversion etc - - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects + - Chris H notes that we should include updates about QuantEcon lectures conversion etc + - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects #### Chris S. **Recent work** + - Released [sphinx-external-toc](https://sphinx-external-toc.readthedocs.io) and integrated in Jupyter-Book - - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) - - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees - - Integration in JB also includes addition of "pluggable" CLI + - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) + - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees + - Integration in JB also includes addition of "pluggable" CLI - Released markdown-it-py v1.0, i.e. fully stable - Released myst-parser v0.15.0, with sphinx v4 support - Should be moving all repositories to sphinx v4 @@ -341,12 +361,13 @@ This is a place to make announcements (without a need for discussion), short upd - Intend to make all plugins for parity with [mdit-py-plugins](https://github.com/executablebooks/mdit-py-plugins), and thus myst-parser extensions **Intended work** + - Update [MyST VS Code extension](https://github.com/executablebooks/myst-language-support) to use new markdown-it plugins - Plus hopefully LSP support - Look into recently finalised Notebook API: https://code.visualstudio.com/api/extension-guides/notebook - Create sphinx-design: An iteration on sphinx-panels, but with the benefit of hindsight, and to more closely follow aspects of [Materials Design](https://material.io/design) and [Material-UI](https://material-ui.com/) - - class names that do not clash with sphinx ones (i.e. container) - - easier to set principle colors and width defaults + - class names that do not clash with sphinx ones (i.e. container) + - easier to set principle colors and width defaults - Either in myst-parser or sphinx-design have nice way to generate stylised post-header banners, with e.g. author, date, read time (see https://github.com/executablebooks/MyST-Parser/issues/372) - Improvements to myst-nb (+ jupyter-cache) - Been gradually working on it, but lot of interconnected parts 😬 @@ -355,15 +376,15 @@ This is a place to make announcements (without a need for discussion), short upd - Better support for Markdown code output - Better support for "multi-level" configuration (cell level > notebook level > conf.py level) - Improve notebook execution and (maybe) drop `auto` mode in favour of `cache` - - Support for dynamic kernel names + - Support for dynamic kernel names - How to handle glue; ideally in a kernel agnostic manner, possily with the new substitution syntax - Plugin CLI in jupyter-book for notebook execution #### Steve - Would like to: - - meet the team - - hear about thoughts on Thebelab as I'm prepping to do some work there + - meet the team + - hear about thoughts on Thebelab as I'm prepping to do some work there #### Berkeley team @@ -376,23 +397,26 @@ This is a place to make announcements (without a need for discussion), short upd - [sphinx-multitoc-numbering PR](https://github.com/executablebooks/jupyter-book/pull/1326) default behaviours (Lead: @mmcky) - Workshop for Theme Specification (Prerequisites?, Preparation?, Timing?) (Lead: @mmcky) - Any new features we should be focussing on from: https://executablebooks.org/en/latest/feature-vote.html - - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) + - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) **Didn't get to the following items** + - Bug issues in Jupyter Book: any important issues to address from: https://github.com/executablebooks/jupyter-book/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug - Jupyter-book in RTD: how can we make it happen!? - - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. + - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. - Theming: I am still keen on creating a shared infrastructure (https://github.com/executablebooks/meta/issues/279) and not necessarily being directly dependent on pydata-sphinx-theme - - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme + - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme - MyST as specification: what does that mean, how to "de-couple" from sphinx? - - What roles/directives/extensions are "core"? - - How to support additional roles/directives/extensions - - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? - - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md + - What roles/directives/extensions are "core"? + - How to support additional roles/directives/extensions + - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? + - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md John S: + - Hiring casual RAs? Chris H: + - Communicating the work we're doing - blog posts, tweets, etc? @executablebooks handle? - Coordinating around deliverables, workstreams, requests for reviews, etc? diff --git a/docs/meetings/2022.md b/docs/meetings/2022.md index bef8ad5..dbf0f76 100644 --- a/docs/meetings/2022.md +++ b/docs/meetings/2022.md @@ -18,7 +18,7 @@ - https://github.com/executablebooks/mystjs - https://executablebooks.github.io/mystjs - And many other PRs updates in the JS world (e.g. docutils state, packaging) -- release of myst-parser v0.17.0 (https://myst-parser.readthedocs.io/en/latest/develop/\_changelog.html), jupyter-cache v0.5.0 (https://jupyter-cache.readthedocs.io/) +- release of myst-parser v0.17.0 (https://myst-parser.readthedocs.io/en/latest/develop/_changelog.html), jupyter-cache v0.5.0 (https://jupyter-cache.readthedocs.io/) - Both feed into https://github.com/executablebooks/MyST-NB/pull/380 - soon-to-be-released sphinx-book-theme (v0.3). in pre-release now but haven't gotten any negative feedback. https://github.com/executablebooks/sphinx-book-theme/releases/tag/v0.3.0rc1 - sphinx-togglebutton also released w/ smaller footprint: https://github.com/executablebooks/sphinx-togglebutton/releases/tag/v0.3.0 diff --git a/docs/meetings/index.md b/docs/meetings/index.md index e25c803..a674fab 100644 --- a/docs/meetings/index.md +++ b/docs/meetings/index.md @@ -11,7 +11,9 @@ If you'd like to discuss something at a meeting, add an entry in the HackMD befo Below are notes from the Executable Books team meetings. ```{toctree} -:maxdepth: 2 +--- +maxdepth: 2 +--- 2022.md 2021.md ``` diff --git a/docs/team.md b/docs/team.md index d2f3985..812cd20 100644 --- a/docs/team.md +++ b/docs/team.md @@ -4,9 +4,9 @@ The Executable Books team is a collection of scientists, scholars, and technolog around the world. We welcome participation and contribution from the community. If you'd like to join the team, please get in touch! -Below are the core `executablebooks` team members. +Below are the core `executablebooks` team members. ## Team ```{include} team_panels_code.txt -``` \ No newline at end of file +``` diff --git a/docs/team_panels_code.txt b/docs/team_panels_code.txt index 3434867..0db8cee 100644 --- a/docs/team_panels_code.txt +++ b/docs/team_panels_code.txt @@ -83,4 +83,3 @@ ```` ````` - \ No newline at end of file diff --git a/docs/tools.md b/docs/tools.md index a29e99b..f380cda 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -3,7 +3,6 @@ There are several major tools that we have developed, or are contributing to, as a part of this project. This page describes a few major components. - ## Jupyter Book Jupyter Book is an open source project for building beautiful, @@ -11,25 +10,25 @@ publication-quality books and documents from computational material. Jupyter Book has the following main features: -* **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can +- **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can write in either Jupyter markdown, or an extended flavor of markdown with publishing features. This includes support for rich syntax such as citations and cross-references, math and equations, and figures. -* **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing +- **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing you to include your code and outputs in your book. You can also write notebooks entirely in markdown to execute when you build your book. -* **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and +- **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and markdown notebooks, execute code and insert the latest outputs into your book. In addition, cache and re-use outputs to be used later. -* **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs +- **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs as you build your documentation, and insert them in-line with your content across pages. -* **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can +- **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can toggle visibility of cells, connect with an online service like Binder, and include interactive outputs from Jupyter. -* **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, +- **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, as well as PDF outputs. -* **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one +- **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one command, like so: `jupyter-book build mybook/` ```{note} @@ -48,15 +47,15 @@ and extensibility of Sphinx with the simplicity and readability of Markdown. MyST has the following main features: -* **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire +- **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire Sphinx documentation in markdown. -* **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, +- **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, allowing you to extend your document via Sphinx extensions. -* **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such +- **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such as line commenting and footnotes. -* **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended +- **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended to add new functionality and outputs for MyST. -* **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown +- **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown (such as Jupyter Notebook markdown) is natively supported by the MyST parser. ## MyST-NB @@ -66,16 +65,16 @@ MyST has the following main features: `MyST-NB` is an open source tool for working with Jupyter Notebooks in the Sphinx ecosystem. It provides the following primary features: -* **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter +- **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter Notebooks into Sphinx documents. -* **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. +- **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. Save time building your documentation without needing to commit your notebook outputs directly into `git`. -* **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown +- **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown allows you to write Sphinx roles and directives in markdown. -* **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs +- **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs as you build your documentation, and insert them across pages. -* **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can +- **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can define the structure of a notebook *in pure-text* making it more diff-able. In addition, there are several options for controlling the look and feel of how your @@ -88,16 +87,15 @@ notebooks are used in your documentation. This is a lightweight Sphinx theme designed to mimic the look-and-feel of an interactive book. It has the following primary features: -* **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** +- **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** for visual elements and functionality. -* **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, +- **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, such as [the Edward Tufte CSS guide](https://edwardtufte.github.io/tufte-css/) -* **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, +- **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, and interactive functionality are all supported. -* **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with +- **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with computational material, connect your site to an online BinderHub for interactive content. - ## Jupyter Cache ([link to documentation](https://jupyter-cache.readthedocs.io)) @@ -112,7 +110,6 @@ text documents), during which it is desired that notebooks can be auto-executed only if the notebook had been modified in a way that may alter its code cell outputs. - ## Markdown-it-py ([link to documentation](https://markdown-it-py.readthedocs.io)) @@ -129,14 +126,12 @@ Here are its main features: - High speed (see our [benchmarking tests](https://markdown-it-py.readthedocs.io/en/latest/other.html#performance)) - [Safe by default](https://markdown-it-py.readthedocs.io/en/latest/other.html#security) - - ## A collection of Sphinx extensions In addition to these major tools described above, the EBP also maintains a number of tools in the Sphinx ecosystem for writing beautiful online books and documents. For example: -* [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) -* [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) -* [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) +- [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) +- [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) +- [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) diff --git a/docs/updates/2020-02-25-hello-world.md b/docs/updates/2020-02-25-hello-world.md index 9c00689..34470f1 100644 --- a/docs/updates/2020-02-25-hello-world.md +++ b/docs/updates/2020-02-25-hello-world.md @@ -1,7 +1,9 @@ # Hello world ```{post} 2020-02-25 -:author: EBP +--- +author: EBP +--- ``` Over the last several years, Jupyter Notebooks have become a staple in the @@ -48,28 +50,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -* **Support casual users equally to power users**. Complicating the feature +- **Support casual users equally to power users**. Complicating the feature space to support a "power user feature" should be done with great care. -* **Build modular components that are useful elsewhere**. Rather than building +- **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -* **Use pre-existing technology where possible**. Rather than re-inventing +- **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -* **Use pre-existing standards where possible**. In the event that we must +- **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -* **Contribute improvements upstream**. Where we utilize pre-existing tools, +- **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -* **Design for the future**. While we have a bit of funding now, it won't last +- **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -* **Users should not need to know anything about the build system**. If they +- **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, etc should not be a requirement. They should only need to use a simple tool to control the process. -* **Don't try to do everything**. Focus our tools on publishing +- **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. ## What does it mean to publish executable documents? diff --git a/docs/updates/2020-08-07-announce-book.md b/docs/updates/2020-08-07-announce-book.md index 1ee8c33..8638265 100644 --- a/docs/updates/2020-08-07-announce-book.md +++ b/docs/updates/2020-08-07-announce-book.md @@ -1,9 +1,11 @@ # Announcing the new Jupyter Book ```{post} 2020-08-07 -:author: EBP -:image: 1 -:excerpt: 2 +--- +author: EBP +image: 1 +excerpt: 2 +--- ``` *Note: this announcement is cross-posted between the [Jupyter Blog](https://blog.jupyter.org) and the [Executable Book Project updates blog](https://executablebooks.org/en/latest/updates.html)* @@ -110,12 +112,12 @@ The biggest change under-the-hood is that Jupyter Book now uses [the Sphinx docu Instead of being a single repository, the old Jupyter Book repository has now been separated into several modular tools. **Each of these tools can be used on their own in your Sphinx documentation**, and they can be coordinated together *via* Jupyter Book: -* **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. -* **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. -* **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). -* **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. -* **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. -* Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). +- **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. +- **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. +- **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). +- **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. +- **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. +- Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). We'll write a more developer-focused post in the future to describe each of these components in more detail. diff --git a/docs/updates/2021-06-18-update-toc.md b/docs/updates/2021-06-18-update-toc.md index 6a5dc5f..7879930 100644 --- a/docs/updates/2021-06-18-update-toc.md +++ b/docs/updates/2021-06-18-update-toc.md @@ -1,9 +1,11 @@ # Migrate your old Table of Contents to the new TOC structure ```{post} 2021-06-17 -:author: EBP -:image: 1 -:excerpt: 2 +--- +author: EBP +image: 1 +excerpt: 2 +--- ``` In Jupyter Book v0.11, we [introduced a new Table of Contents](https://jupyterbook.org/reference/_changelog.html#v0-11-0) structure. @@ -12,7 +14,7 @@ It also introduces the concept of TOC **formats**, which allows you to specify d This is a short guide to explain the differences between the old and new Table of Contents structures, to help you update them. -:::{seealso} +:::\{seealso} If you'd like to automatically convert your Table of Contents, you may also try running the following command: ```bash @@ -112,7 +114,7 @@ parts: - file: publish/netlify ``` -:::{admonition} An alternative structure for single-part books +:::\{admonition} An alternative structure for single-part books If your book only consists of a single part, you could directly add the `chapters` key to the root of your TOC, like so: ```yaml @@ -127,6 +129,7 @@ chapters: - file: publish/gh-pages - file: publish/netlify ``` + ::: ## Step 4: Move the configuration @@ -135,7 +138,6 @@ The new TOC structure has a more explicit configuration structure, and has diffe Because we wish for **all** sections to be numbered, we will keep `numbered: true`, but must move it to a `defaults` key, which makes it a default for all pages in the TOC. - ```yaml root: intro format: jb-book diff --git a/docs/updates/2021-06-5-release-jb-v0.11.1.md b/docs/updates/2021-06-5-release-jb-v0.11.1.md index bbfd0e4..e231671 100644 --- a/docs/updates/2021-06-5-release-jb-v0.11.1.md +++ b/docs/updates/2021-06-5-release-jb-v0.11.1.md @@ -1,9 +1,11 @@ # 🚀 RELEASE: Jupyter Book v0.11.1 ```{post} 2021-06-05 -:author: EBP -:image: 1 -:excerpt: 2 +--- +author: EBP +image: 1 +excerpt: 2 +--- ``` ```{note} @@ -30,7 +32,9 @@ ooooh ``` ```{figure} https://github.com/executablebooks/jupyter-book/blob/master/docs/images/logo-square.svg?raw=true -:width: 100 +--- +width: 100 +--- aaah ``` diff --git a/docs/updates/2021-12-18-agu-2021.md b/docs/updates/2021-12-18-agu-2021.md index f75b6fc..6a70bff 100644 --- a/docs/updates/2021-12-18-agu-2021.md +++ b/docs/updates/2021-12-18-agu-2021.md @@ -1,7 +1,9 @@ # Jupyter Book and MyST at AGU 2021 ```{post} 2021-12-18 -:author: Chris Holdgraf +--- +author: Chris Holdgraf +--- ``` The [AGU 2021 conference](https://www.agu.org/Fall-Meeting) just wrapped up, and Jupyter Book made a few appearances at the conference this year. diff --git a/requirements.txt b/requirements.txt index 890aa65..63cba3e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,4 +9,4 @@ ablog # For the feature voting code ghapi pandas -tabulate \ No newline at end of file +tabulate From 782067fad31b1884e45c0e5e89da5a9948b21113 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 3 Mar 2022 17:07:56 -0800 Subject: [PATCH 5/9] Fix github template --- .github/ISSUE_TEMPLATE/team-meeting.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/team-meeting.md b/.github/ISSUE_TEMPLATE/team-meeting.md index cddebc4..afcca67 100644 --- a/.github/ISSUE_TEMPLATE/team-meeting.md +++ b/.github/ISSUE_TEMPLATE/team-meeting.md @@ -1,6 +1,10 @@ -______________________________________________________________________ - -## name: Team Meeting 📅 about: A team meeting title: 'EBP Team Meeting - {{ MONTH }}' labels: meeting assignees: '' +--- +name: Team Meeting 📅 +about: A team meeting +title: 'EBP Team Meeting - {{ MONTH }}' +labels: meeting +assignees: '' +--- Hello @executablebooks/ebpteam! This is an issue to track the next Executable Books team meeting! Here's some relevant information: @@ -12,11 +16,11 @@ If you'd like to discuss something at the meeting, please add an item to the age ### Before the meeting -- \[ \] Update dates and make sure HackMD information is correct. -- \[ \] Team members add agenda items. +- [ ] Update dates and make sure HackMD information is correct. +- [ ] Team members add agenda items. ### After the meeting -- \[ \] Turn any follow-ups into issues/comments/etc. -- \[ \] Copy the meeting notes to the docs. -- \[ \] Remove notes and clean up HackMD. +- [ ] Turn any follow-ups into issues/comments/etc. +- [ ] Copy the meeting notes to the docs. +- [ ] Remove notes and clean up HackMD. From 0c2ebef3b3d069a8c6d961e85a6e53b414398e96 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sat, 5 Mar 2022 07:12:31 -0800 Subject: [PATCH 6/9] Revert to master --- docs/Makefile | 2 +- docs/_static/custom.css | 2 +- docs/about.md | 26 +- docs/communication.md | 2 - docs/conf.py | 8 +- docs/developer.md | 1 - docs/feature-vote.md | 6 +- docs/gallery.yml | 2 +- docs/index.md | 36 +- docs/meetings/2021.md | 378 +++++++++---------- docs/meetings/2022.md | 2 +- docs/meetings/index.md | 4 +- docs/team.md | 4 +- docs/team_panels_code.txt | 1 + docs/tools.md | 53 +-- docs/updates/2020-02-25-hello-world.md | 20 +- docs/updates/2020-08-07-announce-book.md | 20 +- docs/updates/2021-06-18-update-toc.md | 14 +- docs/updates/2021-06-5-release-jb-v0.11.1.md | 12 +- docs/updates/2021-12-18-agu-2021.md | 4 +- requirements.txt | 2 +- 21 files changed, 279 insertions(+), 320 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index ef45bc1..8533f57 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,4 +20,4 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) live: - sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt + sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt \ No newline at end of file diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 0512ed1..d671601 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -9,4 +9,4 @@ ul.postlist > li > p:first-child { .landing-grid .sd-card-header { background-color: #f3772638; -} +} \ No newline at end of file diff --git a/docs/about.md b/docs/about.md index e10c50e..6c76a41 100644 --- a/docs/about.md +++ b/docs/about.md @@ -24,20 +24,20 @@ professional computational narratives (books, lecture series, articles, etc.) using open source tools. We want users in the scientific, academic, and data science communities to be able to do the following: -- **Write their content in either markdown text files, or Jupyter Notebooks**. +* **Write their content in either markdown text files, or Jupyter Notebooks**. These files include rich content - outputs from running code, references and cross-references, equations, etc. -- **Execute content and cache the results**. Intelligent caching means +* **Execute content and cache the results**. Intelligent caching means that only modified code cells are re-run. -- **Combine cached outputs with content files with a document model**. Using +* **Combine cached outputs with content files with a document model**. Using the excellent [Sphinx](https://www.sphinx-doc.org/en/master/) documentation stack, documents can include many features for publishing, such as equations, cross-references, and citations. -- **Build interactive HTML or publication-quality PDF outputs**. Sometimes +* **Build interactive HTML or publication-quality PDF outputs**. Sometimes users wish to create rich and interactive websites, other times they want to send a high-quality PDF to a publisher. This system will treat both as equal citizens. -- **Control everything above with a simple command-line interface**. Most +* **Control everything above with a simple command-line interface**. Most users should not have to know anything about Sphinx, caching, etc. A simple user interface will hide most of the complexity of this process. @@ -50,28 +50,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -- **Give equal support to casual users and power users**. Complicating the feature +* **Give equal support to casual users and power users**. Complicating the feature space to support a "power user feature" should be done with great care. -- **Build modular components that are useful elsewhere**. Rather than building +* **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -- **Use pre-existing technology where possible**. Rather than re-inventing +* **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -- **Use pre-existing standards where possible**. In the event that we must +* **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -- **Contribute improvements upstream**. Where we utilize pre-existing tools, +* **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -- **Design for the future**. While we have a bit of funding now, it won't last +* **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -- **Users should not need to know anything about the build system**. If they +* **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, and so on should not be a requirement. They should only need to use a simple tool to control the process. -- **Don't try to do everything**. Focus our tools on publishing +* **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. Browse the rest of this site for more information about what we're working diff --git a/docs/communication.md b/docs/communication.md index ef3dece..4c612e2 100644 --- a/docs/communication.md +++ b/docs/communication.md @@ -12,7 +12,6 @@ This is open to anybody, and is a space where people can ask questions and help Please feel free to provide support, advice, etc to anybody on this forum. (comms:issues)= - ## GitHub Issues For conversations around specific actions, tasks, features, etc, we use GitHub issues in each repository. @@ -26,7 +25,6 @@ If you'd like access, please reach out to a core team member to discuss! ## Email % ref: https://github.com/executablebooks/meta/discussions/412 to share password/access - We have an e-mail address at `executablebooks@gmail.com`. All core team members should have access to this email, though it is not currently actively monitored by the team. diff --git a/docs/conf.py b/docs/conf.py index db93b7c..8b67f22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -189,10 +189,10 @@ def build_gallery(app: Sphinx): ) grid_items = "\n".join(grid_items) - # :column: text-center col-6 col-lg-4 - # :card: +my-2 - # :img-top-cls: w-75 m-auto p-2 - # :body: d-none +# :column: text-center col-6 col-lg-4 +# :card: +my-2 +# :img-top-cls: w-75 m-auto p-2 +# :body: d-none panels = f""" ``````{{grid}} 1 2 3 3 diff --git a/docs/developer.md b/docs/developer.md index b5e7e14..83b513a 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -26,7 +26,6 @@ doctree in `python`: ```python import pickle - doc = pickle.load(open("_build/.doctrees/", "rb")) ``` diff --git a/docs/feature-vote.md b/docs/feature-vote.md index d9a40f3..dbc1894 100644 --- a/docs/feature-vote.md +++ b/docs/feature-vote.md @@ -1,5 +1,4 @@ (feature-note)= - # Feature voting board You can help us to prioritise development of new features by leaving a [👍 reaction](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) on the first comment of any `enhancement` issue. @@ -7,6 +6,8 @@ You can help us to prioritise development of new features by leaving a [👍 rea Below is a list of all current enhancement issues from our core repositories,[^a] ordered by 👍 Click the `+` to see more details. +[^a]: The data in this table is updated every day. +
```{include} issue-votes.txt @@ -15,7 +16,6 @@ Click the `+` to see more details.
- @@ -27,5 +27,3 @@ $(document).ready( function () { }); } ); - -[^a]: The data in this table is updated every day. diff --git a/docs/gallery.yml b/docs/gallery.yml index 386acc0..afe44b1 100644 --- a/docs/gallery.yml +++ b/docs/gallery.yml @@ -147,7 +147,7 @@ image: https://raw.githubusercontent.com/rafneta/CienciaDatosPythonCIDE/master/docs/logo.jpg website: https://rafneta.github.io/CienciaDatosPythonCIDE/intro.html - name: "Development Data Partnership" - repository: + repository: image: https://raw.githubusercontent.com/datapartnership/welcome/master/images/logo.png website: https://docs.datapartnership.org - name: "OpenPifPaf Guide" diff --git a/docs/index.md b/docs/index.md index d53ad26..4a4d019 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,31 +7,31 @@ computational narratives using the Jupyter ecosystem. We are the community behind [Jupyter Book](https://jupyterbook.org)--an open source project for building beautiful, publication-quality books and documents from computational material--as well as [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/)--a rich and extensible flavor of Markdown meant for technical documentation and publishing. -::::\{grid} 1 2 2 2 +::::{grid} 1 2 2 2 :class-container: landing-grid -:::\{grid-item-card} +:::{grid-item-card} :padding: 2 For contributors 👩‍💻 ^^^ Read our [Contributing Guide](contributing.md) to learn about the conventions we follow, and see [our community forum](https://github.com/executablebooks/meta/discussions) to ask questions and help others. ::: -:::\{grid-item-card} +:::{grid-item-card} :padding: 2 Be inspired ✨ ^^^ Our [Gallery of Jupyter Books](gallery.md) has contributions from across the community, and [our blog](updates.md) has updates from the community. ::: -:::\{grid-item-card} +:::{grid-item-card} :padding: 2 Tools we build 👍 ^^^ Our [Feature Voting board](feature-vote.md) is an easy way for community members to voice support for features and enhancements. Our [Tools Page](tools.md) also lists many of the tools we build to learn more. ::: -:::\{grid-item-card} +:::{grid-item-card} :padding: 2 About the project ℹ️ ^^^ @@ -39,9 +39,10 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co ::: :::: + ## Acknowledgements -:::\{image} https://pbs.twimg.com/profile_images/1226944724365447169/MzFpwY5P_400x400.png +:::{image} https://pbs.twimg.com/profile_images/1226944724365447169/MzFpwY5P_400x400.png :class: float-left mr-2 rounded :width: 100px ::: @@ -49,12 +50,11 @@ Learn more about [our project's goals and strategy](about.md), see [a list of co The Executable Books Project is supported by several institutions and members of open source projects. In particular, many thanks to the [Sloan Foundation](https://sloan.org) which [provides support for the Executable Books Project](https://sloan.org/grant-detail/9231). + ```{toctree} ---- -maxdepth: 2 -caption: Get Involved -hidden: ---- +:maxdepth: 2 +:caption: Get Involved +:hidden: contributing.md developer.md resources.md @@ -63,21 +63,17 @@ meetings/index.md ``` ```{toctree} ---- -hidden: -caption: Our Projects and Tools ---- +:hidden: +:caption: Our Projects and Tools feature-vote.md gallery.md tools.md ``` ```{toctree} ---- -maxdepth: 2 -caption: About the Project -hidden: ---- +:maxdepth: 2 +:caption: About the Project +:hidden: about.md team.md updates.md diff --git a/docs/meetings/2021.md b/docs/meetings/2021.md index 7a273c5..a0a0e0b 100644 --- a/docs/meetings/2021.md +++ b/docs/meetings/2021.md @@ -16,18 +16,19 @@ ### Team updates -- \[sphinx-exercise\] has been re-factored to make the extension more maintainable. - - https://github.com/executablebooks/sphinx-exercise/pull/37 - - no major user facing changes (except some style updates to output) - - focus: use sphinx internals and AST as much as possible - - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase - - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) - - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html - - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: - - custom styling - - custom options - - ref and numref integration - - autonumbering of nodes (i.e. numref) + +- [sphinx-exercise] has been re-factored to make the extension more maintainable. + - https://github.com/executablebooks/sphinx-exercise/pull/37 + - no major user facing changes (except some style updates to output) + - focus: use sphinx internals and AST as much as possible + - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase + - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) + - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html + - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: + - custom styling + - custom options + - ref and numref integration + - autonumbering of nodes (i.e. numref) - Rowan - Javascript PR merges in - Low hanging fruit is done on the JS side @@ -63,49 +64,49 @@ ### Team updates - Chris H - - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 - - Focusing most of my time trying to document things + un-block people - - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it + - Community strategy for the EOL on our Sloan grant: https://github.com/executablebooks/meta/issues/493 + - Focusing most of my time trying to document things + un-block people + - Have played around with Pradyun's `sphinx-basic-ng` theme and really like it - Steve P - - Progress on thebe: - - Major styles bug fixed - - First cut of status and activate button out - - Changed the docs & examples to use latest build - Thanks to recent RTD changes - - Started a Jupyterlite example - have JupyterLiteServer running in browser - - Next Steps: - - Test & Release - - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) - - Refactoring - - separate jquery layer from low level api (opens up more options for integration) - - document jquery and low level api - - follow through on rename - - Include Jupyterlite kernel option (and generalise) - - Tackle enhancements from Chris S. in thebe / sphinx-thebe + - Progress on thebe: + - Major styles bug fixed + - First cut of status and activate button out + - Changed the docs & examples to use latest build - Thanks to recent RTD changes + - Started a Jupyterlite example - have JupyterLiteServer running in browser + - Next Steps: + - Test & Release + - we need to get an update out, as some projects are pinning earlier releases because of that CSS bug. (will coordinate with Chris H.) + - Refactoring + - separate jquery layer from low level api (opens up more options for integration) + - document jquery and low level api + - follow through on rename + - Include Jupyterlite kernel option (and generalise) + - Tackle enhancements from Chris S. in thebe / sphinx-thebe - Matt M - - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 - - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing - - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. - - General agreement that this would be useful :-) - - Added LaTeX support to sphinx-proof - - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html - - Semantic Admonitions! + - Sphinx V4 Support in https://github.com/executablebooks/jupyter-book/pull/1448 + - Refactor of sphinx-exercise (include LaTeX support for nodes) in final testing + - Would it be useful to have a generalized function / tool to quickly create semantic admonitions that are well-structured? Common Infrastructure? Might be a good way to document admonition -> theme style relationships. + - General agreement that this would be useful :-) + - Added LaTeX support to sphinx-proof + - Example: https://jstac.github.io/continuous_time_mcs/kolmogorov_bwd.html + - Semantic Admonitions! - Chris S - - +1 for `sphinx-basic-ng` and merging focus of themes - - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 - - Made PoC PR to nbclient and nbformat - - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks - - But will it go stale 😬 - - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 - - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe - - Also added merging streams in myst-nb - - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 - - Working with `cpitclaudel` to add "proper" docutils support for myst-parser - - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) - - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" + - +1 for `sphinx-basic-ng` and merging focus of themes + - Participating in https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525 + - Made PoC PR to nbclient and nbformat + - Participated in Jupyter Community Meeting and spoke after with Angus Goose and Tony Fast and maybe set up further talks + - But will it go stale 😬 + - Added `skip-execution` cell tag functionality in nbclient: https://github.com/jupyter/nbclient/pull/151 + - Created myst-nb documentation for sqlalchemy tutorial and fed back to thebe + - Also added merging streams in myst-nb + - Might work with them further on their documentation: https://github.com/sqlalchemy/sqlalchemy/discussions/7138 + - Working with `cpitclaudel` to add "proper" docutils support for myst-parser + - Working with `tanelli` to update markdown-it-py to latest version of markdown-it (and finally fix the more complex url parsing) + - Will also eventually get back to improving jupyter-cache (https://github.com/executablebooks/jupyter-cache/pull/74) and long awaited myst-nb "refactor" - Rowan - - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. - - Need to get back to myst in js work, next week! - - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere + - Have been working on some other open source libraries for templating and exporting to word/latex/pdf from myst. + - Need to get back to myst in js work, next week! + - As implementation starts to happen on the TS/JS/Curvenote side, then it will open opportunities to have discussions around the "core vocabulary" of MyST - what admonitions should be supported everywhere ### Agenda items @@ -114,19 +115,18 @@ - switch to new GitHub project boards? Demo here: https://github.com/orgs/executablebooks/projects/9/views/1 #### Community proposal doc - - Issue for comments/discussion: https://github.com/executablebooks/meta/issues/493 - Proposal text: https://hackmd.io/@choldgraf/HkgAIHtQY - What are some major next steps? - - Investigate the major steps we'd need to take to integrate with the Jupyter community - - Sticking points? - - We'll need to demonstrate that we have a good maintainability story - - Might have questions around the different parts of EBP - - Start to get feedback in the Jupyter ecosystem - - Threads in the discourse + the governance repo - - Talk to stakeholders in that community and see if there are any things we should think about it - - Crystallize the community strategy doc into some concrete next steps - - Decide on an order of operations for things to tackle + - Investigate the major steps we'd need to take to integrate with the Jupyter community + - Sticking points? + - We'll need to demonstrate that we have a good maintainability story + - Might have questions around the different parts of EBP + - Start to get feedback in the Jupyter ecosystem + - Threads in the discourse + the governance repo + - Talk to stakeholders in that community and see if there are any things we should think about it + - Crystallize the community strategy doc into some concrete next steps + - Decide on an order of operations for things to tackle ## September 1st 2021 @@ -137,7 +137,7 @@ If you are joining the team video meeting, sign in below so we know who was here - Rowan Cockett / Curvenote / rowanc1 - Matt McKay / ANU / mmcky - Chris Holdgraf / 2i2c / choldgraf -- Damián Avila / 2i2c / damianavila +- Damián Avila / 2i2c / damianavila - Chris Sewell / EPFL / chrisjsewell ### Reports, updates, and celebrations @@ -145,61 +145,55 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - THEBE: - - - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing - - Opened(opening) tickets on activity board for dicussion - - Refactoring, improving test coverage and docs - - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection + - Some Thebe PRs in recently, and refactoring work started, other PRs ongoing + - Opened(opening) tickets on activity board for dicussion + - Refactoring, improving test coverage and docs + - Extended kernel support for Juptyerlite/pyodide, local proxy and better kernel selection - Some blog post about MyST in my personal blog (Damián) - - - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) - - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) - - Eventually, a part 3 with some coding experiment/stuff + - [Part 1](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-1-the-myst-parser-python-api-usage-in-nikola.html) + - [Part 2](https://damianavila.github.io/blog/posts/a-deep-dive-into-myst-part-2-the-myst-parser-docutils-and-sphinx.html) + - Eventually, a part 3 with some coding experiment/stuff - Sphinx 4 Upgrade (Matt) - - - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 - - Action: Cut a new release right after merge + - myst-nb PR https://github.com/executablebooks/MyST-NB/pull/356 + - Action: Cut a new release right after merge - ReadTheDocs integration (Chris S) - - - That is now working - - PR is open - just waiting on documenting it up - - Action: Needs Doc Update + - That is now working + - PR is open - just waiting on documenting it up + - Action: Needs Doc Update ### Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - Steve: Thebe directions, and future focus - - - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? - - A lot of issues in the repository - - Was a JupyterCon Sprint + a board from that - - Would like to do a bit of planning about what issues etc to tackle next - - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions - - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest + - Setup a Project board on the thebe repo to better plan out work there, in more detail that the Activity Board maybe? + - A lot of issues in the repository + - Was a JupyterCon Sprint + a board from that + - Would like to do a bit of planning about what issues etc to tackle next + - There is definitely the opportunity now to move a bit more quickly and make changes before opening up for contributions + - Priority definely to get the CSS issue fixed so jupyter-book can move to the latest - Rowan: Thoughts on how to move JS-Myst forward (dev branch?) - - - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. - - Might just be an off month?! - - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? - - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. - - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. + - Few-no current dependencies on the work, and could possibly merge/deploy faster than some other repos. + - Might just be an off month?! + - Is there a way that we can ensure a consistent momentum of PRs so that we don't constantly block on people's reviews etc? + - Right now we are at an important early design moment on the JS side. Longer term it should be faster as the PRs will be less complex. + - In the meantime, Chris S will prioritize his EBP stuff on making sure these PRs get reviewed. - Chris H: in-line markdown execution? + - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 + - The difficulty is in the specification + - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) + - An easy first step would be to do "read only inline markdown" + - This is a really popular feature of RMarkdown / Quarto Markdown + - Can you start with the restriction "we should be able to still run every code cell" + - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` + - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. + - You'd then do the execution, and at the end of the time that - - Long conversation about this here: https://discourse.jupyter.org/t/inline-variable-insertion-in-markdown/10525/37 - - The difficulty is in the specification - - mmcky: Related to adding execution to exercise nodes (which we are prototyping) and working out how to get execution embedded in directives. Current approach is through gated directives (which wouldn't work obviously for roles) - - An easy first step would be to do "read only inline markdown" - - This is a really popular feature of RMarkdown / Quarto Markdown - - Can you start with the restriction "we should be able to still run every code cell" - - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` - - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. - - You'd then do the execution, and at the end of the time that # 05th August 2021 @@ -216,107 +210,94 @@ If you are joining the team video meeting, sign in below so we know who was here This is a place to make announcements (without a need for discussion), short updates about what you've been up to, and shout-outs to contributors! We'll read through these at the beginning of the meeting. - Chris Sewell - - - Sphinx Designs - better designed panels, will come into jupyter book at some point - - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten - - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! - - There is also multi-processing on the notebooks! 💥 - - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) - - Javascript! - - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) - - There are same directives and roles from Python - - Same arguments/content - - This is now over to the vscode extension - - MyST as a "standard" - - What roles, directives, blocks to we need that are copied over in another language - - We should get the critical ones in a list somewhere! - - Forming specs in a collaborative way (Identify Good Tools for this?) - -- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) - - - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) - - Adding a directive that is a question, and then how do you add code? - - Directive at the top level and then code and exercise. - - Violates the core design of the Jupyter Notebook -- nested code cells - - Got rid of "nested" concepts - - So how do you have "Gated" directive (open/close) around a few code cells - - This is more compliant with other tools like Jupytext - - Not sure if there is a Gated directive, or prior art in the Sphinx world? - - Other options: - - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) - - Glue? (currently restricted to python, cather than cellId or something) - - Similar ideas playing with at Curvenote! (copy/paste) - - Consideration is mostly from an authorship perspective + - Sphinx Designs - better designed panels, will come into jupyter book at some point + - Jupyter Cache (for executing notebooks --> myst-nb --> JupyterBook) - rewritten + - Decides if code cells are changed and caches outputs. Then can grab the outputs from a local database. There is a CLI! + - There is also multi-processing on the notebooks! 💥 + - There is a new PR [draft](https://github.com/executablebooks/jupyter-cache/pull/74) + - Javascript! + - Added a new repo [docutils](https://github.com/executablebooks/markdown-it-docutils) + - There are same directives and roles from Python + - Same arguments/content + - This is now over to the vscode extension + - MyST as a "standard" + - What roles, directives, blocks to we need that are copied over in another language + - We should get the critical ones in a list somewhere! + - Forming specs in a collaborative way (Identify Good Tools for this?) + +- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) + - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) + - Adding a directive that is a question, and then how do you add code? + - Directive at the top level and then code and exercise. + - Violates the core design of the Jupyter Notebook -- nested code cells + - Got rid of "nested" concepts + - So how do you have "Gated" directive (open/close) around a few code cells + - This is more compliant with other tools like Jupytext + - Not sure if there is a Gated directive, or prior art in the Sphinx world? + - Other options: + - Metadata? Adding tags, etc. (Similar to nbgrader notebooks) + - Glue? (currently restricted to python, cather than cellId or something) + - Similar ideas playing with at Curvenote! (copy/paste) + - Consideration is mostly from an authorship perspective - Steve Purves: Thebe - - - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development - - PR for a small feature - progress indicator - - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better - - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on - - Next up: - - Connecting to many different kernals, and having some basic management on that! + - got started and made some improvements to the build and docs -- yarn, CI issues, local kernel convenience commands for development + - PR for a small feature - progress indicator + - Collaborating a bit with LibreText folks, would like to more and understand how they are using Thebe better + - LibreText made a big change to utilise the @jupyterlab/manager in place of a shim+custom code -- so waiting on that PR coming in before pushing on + - Next up: + - Connecting to many different kernals, and having some basic management on that! - Rowan: MyST in JS - - - Working on myst in JS. Migrating work over to docutils and cleaning up along the way - - - Still basics of various libraries - - - 10 or so PRs up at the moment! - - - Basics: - - sub/sup/abbr - - internationalization? \[each role/directive has a different name\] - - Can generate various dicts to export - - Admonitions - - Math - - amsmath, dollar, math directive - - Figures - - Referencing/numbering PR - - numref/eq/ref - - - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS - - - How are we working with styles? - - - There is some copying back and forth of the .css + - Working on myst in JS. Migrating work over to docutils and cleaning up along the way + - Still basics of various libraries + + - 10 or so PRs up at the moment! + - Basics: + - sub/sup/abbr + - internationalization? [each role/directive has a different name] + - Can generate various dicts to export + - Admonitions + - Math + - amsmath, dollar, math directive + - Figures + - Referencing/numbering PR + - numref/eq/ref + - Working to remove all of the markdown-it-myst functionality --> docutils w/ review from ChrisS + - How are we working with styles? + - There is some copying back and forth of the .css - Damián - - - Learning Myst internals working in the Nikola + Myst story - - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community - - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? + - Learning Myst internals working in the Nikola + Myst story + - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community + - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? ## Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - NAME: ITEM (EXPECTED TIME TO DISCUSS) - + - Discuss team activity board proposal (https://github.com/executablebooks/meta/issues/441) - - The goal of this board is to coordinate and plan our major work items, to make it clear who is working on what, and to help signal boost items for review/discussion. - Is this board structure worth trying as-is or are there major changes to make to it? - If we want to try this process, perhaps we should use this meeting to add some initial items to the board? **Discussion:** - 1. This was discussed with the team and we agreed to use it this month to see how it works. -1. Any suggestions to simplify or improve the Activity Board was encouraged. -1. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. -1. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get - more distributed reviews across the team. -1. We should add the Activity Board as a standing discussion point for the monthly meeting +2. Any suggestions to simplify or improve the Activity Board was encouraged. +3. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. +4. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get +more distributed reviews across the team. +5. We should add the Activity Board as a standing discussion point for the monthly meeting -- Steve: Next Steps for Thebe - - Refactoring the one big file into more manageable chunks - - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all - - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 + - Steve: Next Steps for Thebe + - Refactoring the one big file into more manageable chunks + - More tests - current test coverage is poor, PRs go green but not much really covered which is maybe worse than no tests at all + - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 **Discussion:** - -1. This was discussed in the Reports section. +1. This was discussed in the Reports section. ## July 1st, 2021 @@ -338,17 +319,16 @@ This is a place to make announcements (without a need for discussion), short upd - QuantEcon: 4/5 Projects running Jupyter Book (remaining: julia) - ANU Team: Working on Support for Individual Page PDF (via LaTeX) generation (Lead: @mmcky) - - Chris H notes that we should include updates about QuantEcon lectures conversion etc - - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects + - Chris H notes that we should include updates about QuantEcon lectures conversion etc + - @mmcky to add links to executable books gallery to QuantEcon jupyter-book powered projects #### Chris S. **Recent work** - - Released [sphinx-external-toc](https://sphinx-external-toc.readthedocs.io) and integrated in Jupyter-Book - - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) - - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees - - Integration in JB also includes addition of "pluggable" CLI + - Removes a lot of code from jupyter-book 😄, moving towards JB just being a thin wrapper for sphinx-extensions (last part is basically the `_config.yml`) + - Bit of a balancing act between; ease of use/understandanding, having a clear schema, having all the functionality of sphinx toctrees + - Integration in JB also includes addition of "pluggable" CLI - Released markdown-it-py v1.0, i.e. fully stable - Released myst-parser v0.15.0, with sphinx v4 support - Should be moving all repositories to sphinx v4 @@ -361,13 +341,12 @@ This is a place to make announcements (without a need for discussion), short upd - Intend to make all plugins for parity with [mdit-py-plugins](https://github.com/executablebooks/mdit-py-plugins), and thus myst-parser extensions **Intended work** - - Update [MyST VS Code extension](https://github.com/executablebooks/myst-language-support) to use new markdown-it plugins - Plus hopefully LSP support - Look into recently finalised Notebook API: https://code.visualstudio.com/api/extension-guides/notebook - Create sphinx-design: An iteration on sphinx-panels, but with the benefit of hindsight, and to more closely follow aspects of [Materials Design](https://material.io/design) and [Material-UI](https://material-ui.com/) - - class names that do not clash with sphinx ones (i.e. container) - - easier to set principle colors and width defaults + - class names that do not clash with sphinx ones (i.e. container) + - easier to set principle colors and width defaults - Either in myst-parser or sphinx-design have nice way to generate stylised post-header banners, with e.g. author, date, read time (see https://github.com/executablebooks/MyST-Parser/issues/372) - Improvements to myst-nb (+ jupyter-cache) - Been gradually working on it, but lot of interconnected parts 😬 @@ -376,15 +355,15 @@ This is a place to make announcements (without a need for discussion), short upd - Better support for Markdown code output - Better support for "multi-level" configuration (cell level > notebook level > conf.py level) - Improve notebook execution and (maybe) drop `auto` mode in favour of `cache` - - Support for dynamic kernel names + - Support for dynamic kernel names - How to handle glue; ideally in a kernel agnostic manner, possily with the new substitution syntax - Plugin CLI in jupyter-book for notebook execution #### Steve - Would like to: - - meet the team - - hear about thoughts on Thebelab as I'm prepping to do some work there + - meet the team + - hear about thoughts on Thebelab as I'm prepping to do some work there #### Berkeley team @@ -397,26 +376,23 @@ This is a place to make announcements (without a need for discussion), short upd - [sphinx-multitoc-numbering PR](https://github.com/executablebooks/jupyter-book/pull/1326) default behaviours (Lead: @mmcky) - Workshop for Theme Specification (Prerequisites?, Preparation?, Timing?) (Lead: @mmcky) - Any new features we should be focussing on from: https://executablebooks.org/en/latest/feature-vote.html - - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) + - One possibility: `sphinx-margin` (https://github.com/executablebooks/meta/discussions/409) **Didn't get to the following items** - - Bug issues in Jupyter Book: any important issues to address from: https://github.com/executablebooks/jupyter-book/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug - Jupyter-book in RTD: how can we make it happen!? - - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. + - Chris H can give a short update from a conversation he had with Eric and Juan at RTD a few days ago. - Theming: I am still keen on creating a shared infrastructure (https://github.com/executablebooks/meta/issues/279) and not necessarily being directly dependent on pydata-sphinx-theme - - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme + - Although @choldgraf mentioned about possible funding from NumFocus for pydata-sphinx-theme - MyST as specification: what does that mean, how to "de-couple" from sphinx? - - What roles/directives/extensions are "core"? - - How to support additional roles/directives/extensions - - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? - - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md + - What roles/directives/extensions are "core"? + - How to support additional roles/directives/extensions + - How does this tie in with "JavaScript" work (i.e. editor tools in VS Code, JupyterLab, etc)? + - Some notes in https://github.com/executablebooks/markdown-it-myst/blob/directives/docs/design.md John S: - - Hiring casual RAs? Chris H: - - Communicating the work we're doing - blog posts, tweets, etc? @executablebooks handle? - Coordinating around deliverables, workstreams, requests for reviews, etc? diff --git a/docs/meetings/2022.md b/docs/meetings/2022.md index dbf0f76..bef8ad5 100644 --- a/docs/meetings/2022.md +++ b/docs/meetings/2022.md @@ -18,7 +18,7 @@ - https://github.com/executablebooks/mystjs - https://executablebooks.github.io/mystjs - And many other PRs updates in the JS world (e.g. docutils state, packaging) -- release of myst-parser v0.17.0 (https://myst-parser.readthedocs.io/en/latest/develop/_changelog.html), jupyter-cache v0.5.0 (https://jupyter-cache.readthedocs.io/) +- release of myst-parser v0.17.0 (https://myst-parser.readthedocs.io/en/latest/develop/\_changelog.html), jupyter-cache v0.5.0 (https://jupyter-cache.readthedocs.io/) - Both feed into https://github.com/executablebooks/MyST-NB/pull/380 - soon-to-be-released sphinx-book-theme (v0.3). in pre-release now but haven't gotten any negative feedback. https://github.com/executablebooks/sphinx-book-theme/releases/tag/v0.3.0rc1 - sphinx-togglebutton also released w/ smaller footprint: https://github.com/executablebooks/sphinx-togglebutton/releases/tag/v0.3.0 diff --git a/docs/meetings/index.md b/docs/meetings/index.md index a674fab..e25c803 100644 --- a/docs/meetings/index.md +++ b/docs/meetings/index.md @@ -11,9 +11,7 @@ If you'd like to discuss something at a meeting, add an entry in the HackMD befo Below are notes from the Executable Books team meetings. ```{toctree} ---- -maxdepth: 2 ---- +:maxdepth: 2 2022.md 2021.md ``` diff --git a/docs/team.md b/docs/team.md index 812cd20..d2f3985 100644 --- a/docs/team.md +++ b/docs/team.md @@ -4,9 +4,9 @@ The Executable Books team is a collection of scientists, scholars, and technolog around the world. We welcome participation and contribution from the community. If you'd like to join the team, please get in touch! -Below are the core `executablebooks` team members. +Below are the core `executablebooks` team members. ## Team ```{include} team_panels_code.txt -``` +``` \ No newline at end of file diff --git a/docs/team_panels_code.txt b/docs/team_panels_code.txt index 0db8cee..3434867 100644 --- a/docs/team_panels_code.txt +++ b/docs/team_panels_code.txt @@ -83,3 +83,4 @@ ```` ````` + \ No newline at end of file diff --git a/docs/tools.md b/docs/tools.md index f380cda..a29e99b 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -3,6 +3,7 @@ There are several major tools that we have developed, or are contributing to, as a part of this project. This page describes a few major components. + ## Jupyter Book Jupyter Book is an open source project for building beautiful, @@ -10,25 +11,25 @@ publication-quality books and documents from computational material. Jupyter Book has the following main features: -- **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can +* **[Write publication-quality content in markdown](https://jupyterbook.org/content-types/markdown.html)**. You can write in either Jupyter markdown, or an extended flavor of markdown with publishing features. This includes support for rich syntax such as citations and cross-references, math and equations, and figures. -- **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing +* **[Write content in Jupyter Notebooks](https://jupyterbook.org/content-types/notebooks.html)**, allowing you to include your code and outputs in your book. You can also write notebooks entirely in markdown to execute when you build your book. -- **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and +* **[Execute and cache your book's content](https://jupyterbook.org/content/execute.html)**. For `.ipynb` and markdown notebooks, execute code and insert the latest outputs into your book. In addition, cache and re-use outputs to be used later. -- **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs +* **[Insert notebook outputs into your content](https://jupyterbook.org/content/executable/output-insert.html)**. Generate outputs as you build your documentation, and insert them in-line with your content across pages. -- **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can +* **[Add interactivity to your book](https://jupyterbook.org/interactive/launchbuttons.html)**. You can toggle visibility of cells, connect with an online service like Binder, and include interactive outputs from Jupyter. -- **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, +* **[Generate a variety of outputs](https://jupyterbook.org/start/build.html)**, including single- and multi-page websites, as well as PDF outputs. -- **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one +* **[A command-line interface](https://jupyterbook.org/reference/cli.html)** to quickly generate your books with one command, like so: `jupyter-book build mybook/` ```{note} @@ -47,15 +48,15 @@ and extensibility of Sphinx with the simplicity and readability of Markdown. MyST has the following main features: -- **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire +* **[A markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/using/intro.html#parse-with-sphinx)**. You can write your entire Sphinx documentation in markdown. -- **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, +* **[Call Sphinx directives and roles from within Markdown](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#syntax-directives)**, allowing you to extend your document via Sphinx extensions. -- **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such +* **[Extended Markdown syntax for useful rST features](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#extended-block-tokens)**, such as line commenting and footnotes. -- **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended +* **[A Sphinx-independent parser of MyST markdown](https://myst-parser.readthedocs.io/en/latest/using/use_api.html)** that can be extended to add new functionality and outputs for MyST. -- **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown +* **[A superset of CommonMark markdown](https://commonmark.org/)**. Any CommonMark markdown (such as Jupyter Notebook markdown) is natively supported by the MyST parser. ## MyST-NB @@ -65,16 +66,16 @@ MyST has the following main features: `MyST-NB` is an open source tool for working with Jupyter Notebooks in the Sphinx ecosystem. It provides the following primary features: -- **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter +* **[Parse ipynb files in Sphinx](https://myst-nb.readthedocs.io/en/latest/#installation)**. Directly convert Jupyter Notebooks into Sphinx documents. -- **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. +* **[Execute and Cache your notebook content](https://myst-nb.readthedocs.io/en/latest/use/execute.html)**. Save time building your documentation without needing to commit your notebook outputs directly into `git`. -- **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown +* **[Write MyST Markdown](https://myst-nb.readthedocs.io/en/latest/use/myst.html)**. MyST Markdown allows you to write Sphinx roles and directives in markdown. -- **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs +* **[Insert notebook outputs into your content](https://myst-nb.readthedocs.io/en/latest/use/glue.html)**. Generate outputs as you build your documentation, and insert them across pages. -- **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can +* **[Write Jupyter Notebooks entirely with Markdown](https://myst-nb.readthedocs.io/en/latest/use/markdown.html)**. You can define the structure of a notebook *in pure-text* making it more diff-able. In addition, there are several options for controlling the look and feel of how your @@ -87,15 +88,16 @@ notebooks are used in your documentation. This is a lightweight Sphinx theme designed to mimic the look-and-feel of an interactive book. It has the following primary features: -- **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** +* **[Bootstrap 4](https://getbootstrap.com/docs/4.0/getting-started/introduction/)** for visual elements and functionality. -- **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, +* **[Flexible content layout](https://sphinx-book-theme.readthedocs.io/en/latest/content-blocks.html)** that is inspired by beautiful online books, such as [the Edward Tufte CSS guide](https://edwardtufte.github.io/tufte-css/) -- **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, +* **[Visual classes designed for Jupyter Notebooks](https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html)**. Cell inputs, outputs, and interactive functionality are all supported. -- **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with +* **[Launch buttons for online interactivity](https://sphinx-book-theme.readthedocs.io/en/latest/launch.html)**. For pages that are built with computational material, connect your site to an online BinderHub for interactive content. + ## Jupyter Cache ([link to documentation](https://jupyter-cache.readthedocs.io)) @@ -110,6 +112,7 @@ text documents), during which it is desired that notebooks can be auto-executed only if the notebook had been modified in a way that may alter its code cell outputs. + ## Markdown-it-py ([link to documentation](https://markdown-it-py.readthedocs.io)) @@ -126,12 +129,14 @@ Here are its main features: - High speed (see our [benchmarking tests](https://markdown-it-py.readthedocs.io/en/latest/other.html#performance)) - [Safe by default](https://markdown-it-py.readthedocs.io/en/latest/other.html#security) + + ## A collection of Sphinx extensions In addition to these major tools described above, the EBP also maintains a number of tools in the Sphinx ecosystem for writing beautiful online books and documents. For example: -- [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) -- [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) -- [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) +* [`sphinx-copybutton`](https://sphinx-copybutton.readthedocs.io/) +* [`sphinx-togglebutton`](https://sphinx-togglebutton.readthedocs.io/) +* [`sphinx-panels`](https://sphinx-panels.readthedocs.io/en/latest/) diff --git a/docs/updates/2020-02-25-hello-world.md b/docs/updates/2020-02-25-hello-world.md index 34470f1..9c00689 100644 --- a/docs/updates/2020-02-25-hello-world.md +++ b/docs/updates/2020-02-25-hello-world.md @@ -1,9 +1,7 @@ # Hello world ```{post} 2020-02-25 ---- -author: EBP ---- +:author: EBP ``` Over the last several years, Jupyter Notebooks have become a staple in the @@ -50,28 +48,28 @@ In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: -- **Support casual users equally to power users**. Complicating the feature +* **Support casual users equally to power users**. Complicating the feature space to support a "power user feature" should be done with great care. -- **Build modular components that are useful elsewhere**. Rather than building +* **Build modular components that are useful elsewhere**. Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. -- **Use pre-existing technology where possible**. Rather than re-inventing +* **Use pre-existing technology where possible**. Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. -- **Use pre-existing standards where possible**. In the event that we must +* **Use pre-existing standards where possible**. In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. -- **Contribute improvements upstream**. Where we utilize pre-existing tools, +* **Contribute improvements upstream**. Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. -- **Design for the future**. While we have a bit of funding now, it won't last +* **Design for the future**. While we have a bit of funding now, it won't last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. -- **Users should not need to know anything about the build system**. If they +* **Users should not need to know anything about the build system**. If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, etc should not be a requirement. They should only need to use a simple tool to control the process. -- **Don't try to do everything**. Focus our tools on publishing +* **Don't try to do everything**. Focus our tools on publishing computational documents with reasonable choices made for the user. ## What does it mean to publish executable documents? diff --git a/docs/updates/2020-08-07-announce-book.md b/docs/updates/2020-08-07-announce-book.md index 8638265..1ee8c33 100644 --- a/docs/updates/2020-08-07-announce-book.md +++ b/docs/updates/2020-08-07-announce-book.md @@ -1,11 +1,9 @@ # Announcing the new Jupyter Book ```{post} 2020-08-07 ---- -author: EBP -image: 1 -excerpt: 2 ---- +:author: EBP +:image: 1 +:excerpt: 2 ``` *Note: this announcement is cross-posted between the [Jupyter Blog](https://blog.jupyter.org) and the [Executable Book Project updates blog](https://executablebooks.org/en/latest/updates.html)* @@ -112,12 +110,12 @@ The biggest change under-the-hood is that Jupyter Book now uses [the Sphinx docu Instead of being a single repository, the old Jupyter Book repository has now been separated into several modular tools. **Each of these tools can be used on their own in your Sphinx documentation**, and they can be coordinated together *via* Jupyter Book: -- **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. -- **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. -- **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). -- **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. -- **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. -- Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). +* **[The MyST markdown parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/)** allows you to write fully-featured Sphinx documentation in Markdown. +* **[MyST-NB](https://myst-nb.readthedocs.io/en/latest/)** is an `.ipynb` parser for Sphinx that allows you to use MyST Markdown in your notebooks. It also provides tools for execution, cacheing, and variable insertion of Jupyter Notebooks in Sphinx. +* **[The Sphinx Book Theme](https://myst-nb.readthedocs.io/en/latest/)** is a beautiful book-like theme for Sphinx, build on top of the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/). +* **[Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/)** allows you to execute a collection of notebooks and store their outputs in a hashed database. This lets you cache your notebook's output without including it in the `.ipynb` file itself. +* **[Sphinx-Thebe](https://sphinx-thebe.readthedocs.io/en/latest/)** converts your "static" HTML page into an interactive page with code cells that are run remotely by a Binder kernel. +* Finally, Jupyter Book also supports a growing collection of Sphinx extensions, such as [sphinx-copybutton](https://sphinx-copybutton.readthedocs.io/en/latest/), [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/), and [sphinx-panels](https://sphinx-panels.readthedocs.io/en/latest/?badge=latest). We'll write a more developer-focused post in the future to describe each of these components in more detail. diff --git a/docs/updates/2021-06-18-update-toc.md b/docs/updates/2021-06-18-update-toc.md index 7879930..6a5dc5f 100644 --- a/docs/updates/2021-06-18-update-toc.md +++ b/docs/updates/2021-06-18-update-toc.md @@ -1,11 +1,9 @@ # Migrate your old Table of Contents to the new TOC structure ```{post} 2021-06-17 ---- -author: EBP -image: 1 -excerpt: 2 ---- +:author: EBP +:image: 1 +:excerpt: 2 ``` In Jupyter Book v0.11, we [introduced a new Table of Contents](https://jupyterbook.org/reference/_changelog.html#v0-11-0) structure. @@ -14,7 +12,7 @@ It also introduces the concept of TOC **formats**, which allows you to specify d This is a short guide to explain the differences between the old and new Table of Contents structures, to help you update them. -:::\{seealso} +:::{seealso} If you'd like to automatically convert your Table of Contents, you may also try running the following command: ```bash @@ -114,7 +112,7 @@ parts: - file: publish/netlify ``` -:::\{admonition} An alternative structure for single-part books +:::{admonition} An alternative structure for single-part books If your book only consists of a single part, you could directly add the `chapters` key to the root of your TOC, like so: ```yaml @@ -129,7 +127,6 @@ chapters: - file: publish/gh-pages - file: publish/netlify ``` - ::: ## Step 4: Move the configuration @@ -138,6 +135,7 @@ The new TOC structure has a more explicit configuration structure, and has diffe Because we wish for **all** sections to be numbered, we will keep `numbered: true`, but must move it to a `defaults` key, which makes it a default for all pages in the TOC. + ```yaml root: intro format: jb-book diff --git a/docs/updates/2021-06-5-release-jb-v0.11.1.md b/docs/updates/2021-06-5-release-jb-v0.11.1.md index e231671..bbfd0e4 100644 --- a/docs/updates/2021-06-5-release-jb-v0.11.1.md +++ b/docs/updates/2021-06-5-release-jb-v0.11.1.md @@ -1,11 +1,9 @@ # 🚀 RELEASE: Jupyter Book v0.11.1 ```{post} 2021-06-05 ---- -author: EBP -image: 1 -excerpt: 2 ---- +:author: EBP +:image: 1 +:excerpt: 2 ``` ```{note} @@ -32,9 +30,7 @@ ooooh ``` ```{figure} https://github.com/executablebooks/jupyter-book/blob/master/docs/images/logo-square.svg?raw=true ---- -width: 100 ---- +:width: 100 aaah ``` diff --git a/docs/updates/2021-12-18-agu-2021.md b/docs/updates/2021-12-18-agu-2021.md index 6a70bff..f75b6fc 100644 --- a/docs/updates/2021-12-18-agu-2021.md +++ b/docs/updates/2021-12-18-agu-2021.md @@ -1,9 +1,7 @@ # Jupyter Book and MyST at AGU 2021 ```{post} 2021-12-18 ---- -author: Chris Holdgraf ---- +:author: Chris Holdgraf ``` The [AGU 2021 conference](https://www.agu.org/Fall-Meeting) just wrapped up, and Jupyter Book made a few appearances at the conference this year. diff --git a/requirements.txt b/requirements.txt index 63cba3e..890aa65 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,4 +9,4 @@ ablog # For the feature voting code ghapi pandas -tabulate +tabulate \ No newline at end of file From 3e0be712a092f2acf5b7acc8834a4f6b50ea3a21 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sat, 5 Mar 2022 07:14:44 -0800 Subject: [PATCH 7/9] Update pre-commit --- .pre-commit-config.yaml | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 50de92c..2ebe6b8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -21,12 +21,16 @@ repos: hooks: - id: black - - repo: https://github.com/executablebooks/mdformat - rev: 0.7.13 - hooks: - - id: mdformat - files: docs/* - additional_dependencies: - - mdformat-gfm - - mdformat-myst - - mdformat-black + # Disabling mdformat because it doesn't currently work with MyST extensions + # We should uncomment when this is supported. + # ref: https://github.com/executablebooks/mdformat-myst/pull/9 + # + # - repo: https://github.com/executablebooks/mdformat + # rev: 0.7.13 + # hooks: + # - id: mdformat + # files: docs/* + # additional_dependencies: + # - mdformat-gfm + # - mdformat-myst + # - mdformat-black From d565cf231269332bf391e3b820a55b7f72df7866 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sat, 5 Mar 2022 07:16:56 -0800 Subject: [PATCH 8/9] Reformat --- .gitignore | 5 ++- docs/Makefile | 2 +- docs/_static/custom.css | 2 +- docs/conf.py | 8 ++-- docs/gallery.yml | 2 +- docs/meetings/2021.md | 22 +++++----- docs/team.md | 4 +- docs/team_panels_code.txt | 86 --------------------------------------- requirements.txt | 2 +- 9 files changed, 25 insertions(+), 108 deletions(-) delete mode 100644 docs/team_panels_code.txt diff --git a/.gitignore b/.gitignore index 118b1e8..c43aa6e 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,9 @@ docs/_build *.ipynb_checkpoints docs/contributing.md .vscode/ +.tox/ + +# Programmatically generated docs docs/gallery.txt docs/issue-votes.txt -.tox/ +docs/team_panels_code.txt diff --git a/docs/Makefile b/docs/Makefile index 8533f57..ef45bc1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,4 +20,4 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) live: - sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt \ No newline at end of file + sphinx-autobuild . _build/html/ --ignore */contributing.md --ignore */gallery.txt --ignore */team_panels_code.txt diff --git a/docs/_static/custom.css b/docs/_static/custom.css index d671601..0512ed1 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -9,4 +9,4 @@ ul.postlist > li > p:first-child { .landing-grid .sd-card-header { background-color: #f3772638; -} \ No newline at end of file +} diff --git a/docs/conf.py b/docs/conf.py index 8b67f22..db93b7c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -189,10 +189,10 @@ def build_gallery(app: Sphinx): ) grid_items = "\n".join(grid_items) -# :column: text-center col-6 col-lg-4 -# :card: +my-2 -# :img-top-cls: w-75 m-auto p-2 -# :body: d-none + # :column: text-center col-6 col-lg-4 + # :card: +my-2 + # :img-top-cls: w-75 m-auto p-2 + # :body: d-none panels = f""" ``````{{grid}} 1 2 3 3 diff --git a/docs/gallery.yml b/docs/gallery.yml index afe44b1..386acc0 100644 --- a/docs/gallery.yml +++ b/docs/gallery.yml @@ -147,7 +147,7 @@ image: https://raw.githubusercontent.com/rafneta/CienciaDatosPythonCIDE/master/docs/logo.jpg website: https://rafneta.github.io/CienciaDatosPythonCIDE/intro.html - name: "Development Data Partnership" - repository: + repository: image: https://raw.githubusercontent.com/datapartnership/welcome/master/images/logo.png website: https://docs.datapartnership.org - name: "OpenPifPaf Guide" diff --git a/docs/meetings/2021.md b/docs/meetings/2021.md index a0a0e0b..246c3cd 100644 --- a/docs/meetings/2021.md +++ b/docs/meetings/2021.md @@ -17,12 +17,12 @@ ### Team updates -- [sphinx-exercise] has been re-factored to make the extension more maintainable. +- [sphinx-exercise] has been re-factored to make the extension more maintainable. - https://github.com/executablebooks/sphinx-exercise/pull/37 - no major user facing changes (except some style updates to output) - focus: use sphinx internals and AST as much as possible - comments: found numref integration pretty hard to get right as numref is implemented (in part) in the translator phase - - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) + - reviews: Welcome any and all comments, also would love to chat with anyone with knowledge on Sphinx references (ref and numref) - preview: https://61a58d957549766565b7eb2a--peaceful-feynman-936ca4.netlify.app/intro.html - todo: write developer notes and lessons learnt for a general "admonition factory" with support for: - custom styling @@ -121,7 +121,7 @@ - Investigate the major steps we'd need to take to integrate with the Jupyter community - Sticking points? - We'll need to demonstrate that we have a good maintainability story - - Might have questions around the different parts of EBP + - Might have questions around the different parts of EBP - Start to get feedback in the Jupyter ecosystem - Threads in the discourse + the governance repo - Talk to stakeholders in that community and see if there are any things we should think about it @@ -137,7 +137,7 @@ If you are joining the team video meeting, sign in below so we know who was here - Rowan Cockett / Curvenote / rowanc1 - Matt McKay / ANU / mmcky - Chris Holdgraf / 2i2c / choldgraf -- Damián Avila / 2i2c / damianavila +- Damián Avila / 2i2c / damianavila - Chris Sewell / EPFL / chrisjsewell ### Reports, updates, and celebrations @@ -192,7 +192,7 @@ Let's collect all potential agenda items here before the start of the meeting. W - Can you start with the restriction "we should be able to still run every code cell" - From a user's perspective, you'd just want them to be able to put in variables with some kind of syntax e.g. `{{ }}` - You'd need to go through the markdown cells and look for the `{{ }}` syntax and know what kinds of variables that you need. - - You'd then do the execution, and at the end of the time that + - You'd then do the execution, and at the end of the time that # 05th August 2021 @@ -225,7 +225,7 @@ This is a place to make announcements (without a need for discussion), short upd - We should get the critical ones in a list somewhere! - Forming specs in a collaborative way (Identify Good Tools for this?) -- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) +- Matt McKay: Taken over maintaining sphinx-proof and sphinx-exercise (looking into enabling execution through gated directives as a proof of concept) - "enabling execution in directives" (https://github.com/executablebooks/sphinx-exercise/issues/24) - Adding a directive that is a question, and then how do you add code? - Directive at the top level and then code and exercise. @@ -251,7 +251,7 @@ This is a place to make announcements (without a need for discussion), short upd - Rowan: MyST in JS - Working on myst in JS. Migrating work over to docutils and cleaning up along the way - Still basics of various libraries - + - 10 or so PRs up at the moment! - Basics: - sub/sup/abbr @@ -270,14 +270,14 @@ This is a place to make announcements (without a need for discussion), short upd - Damián - Learning Myst internals working in the Nikola + Myst story - Probably writing a series of blog posts to push discussion forward about things I have found and engage the community - - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? + - MyST as a “standard” > What roles, directives, blocks do we need copied over Python (independent from Docutils/Sphinx)? Do we need a docultils/sphinx free Py representation of the "standard"? ## Agenda items Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. - NAME: ITEM (EXPECTED TIME TO DISCUSS) - + - Discuss team activity board proposal (https://github.com/executablebooks/meta/issues/441) - The goal of this board is to coordinate and plan our major work items, to make it clear who is working on what, and to help signal boost items for review/discussion. - Is this board structure worth trying as-is or are there major changes to make to it? @@ -285,7 +285,7 @@ Let's collect all potential agenda items here before the start of the meeting. W **Discussion:** 1. This was discussed with the team and we agreed to use it this month to see how it works. -2. Any suggestions to simplify or improve the Activity Board was encouraged. +2. Any suggestions to simplify or improve the Activity Board was encouraged. 3. We focused on keeping the activity board pretty high level for cross-cutting communication and to help coordinate. 4. We also discussed keeping an eye on the `Request for Review` board to get visibility on PR's that need review and get more distributed reviews across the team. @@ -297,7 +297,7 @@ more distributed reviews across the team. - Kernel Status & Management - as part of refactor want to make it easier to get status of the kernel and lay ground work for the issues asking for: Kernel Status, Multiple Kernels and Jupyterlite connectivity; 412, 349, 271 **Discussion:** -1. This was discussed in the Reports section. +1. This was discussed in the Reports section. ## July 1st, 2021 diff --git a/docs/team.md b/docs/team.md index d2f3985..812cd20 100644 --- a/docs/team.md +++ b/docs/team.md @@ -4,9 +4,9 @@ The Executable Books team is a collection of scientists, scholars, and technolog around the world. We welcome participation and contribution from the community. If you'd like to join the team, please get in touch! -Below are the core `executablebooks` team members. +Below are the core `executablebooks` team members. ## Team ```{include} team_panels_code.txt -``` \ No newline at end of file +``` diff --git a/docs/team_panels_code.txt b/docs/team_panels_code.txt deleted file mode 100644 index 3434867..0000000 --- a/docs/team_panels_code.txt +++ /dev/null @@ -1,86 +0,0 @@ - -`````{grid} 2 2 4 4 -:gutter: 1 2 2 3 - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/1839645?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/choldgraf -:class: sd-rounded-circle -``` -```` - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/2997570?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/chrisjsewell -:class: sd-rounded-circle -``` -```` - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/3275109?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/hukkin -:class: sd-rounded-circle -``` -```` - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/3887684?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/jstac -:class: sd-rounded-circle -``` -```` - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/8263752?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/mmcky -:class: sd-rounded-circle -``` -```` - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/33075058?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/najuzilu -:class: sd-rounded-circle -``` -```` - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/3275593?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/pradyunsg -:class: sd-rounded-circle -``` -```` - - -````{grid-item} -```{image} https://avatars.githubusercontent.com/u/6542997?v=4 -:height: 150px -:alt: avatar -:target: https://github.com/AakashGfude -:class: sd-rounded-circle -``` -```` - -````` - \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 890aa65..63cba3e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,4 +9,4 @@ ablog # For the feature voting code ghapi pandas -tabulate \ No newline at end of file +tabulate From 12e36f50b20f2a82b7ccd41895677f13c9750bb2 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sun, 21 Aug 2022 07:18:17 +0200 Subject: [PATCH 9/9] Fix link --- docs/gallery.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gallery.yml b/docs/gallery.yml index 60e31cf..6ca4d99 100644 --- a/docs/gallery.yml +++ b/docs/gallery.yml @@ -9,7 +9,7 @@ - name: "eChem: Computational Chemistry from Laptop to HPC" website: https://kthpanor.github.io/echem/ repository: https://github.com/kthpanor/echem - image: https://raw.githubusercontent.com/kthpanor/echem/master/logo.png + image: https://kthpanor.github.io/echem/_static/logo.png - name: Data Science for Finance website: https://ledatascifi.github.io repository: https://github.com/LeDataSciFi/ledatascifi-2022