{"id":13565680,"url":"https://github.com/outerbounds/nbdoc-docusaurus","last_synced_at":"2025-04-22T21:31:54.620Z","repository":{"id":42981674,"uuid":"472628116","full_name":"outerbounds/nbdoc-docusaurus","owner":"outerbounds","description":"Create testable, reproduceable documentation with Jupyter notebooks","archived":false,"fork":false,"pushed_at":"2022-07-19T15:53:24.000Z","size":32538,"stargazers_count":51,"open_issues_count":2,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T04:23:27.805Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://outerbounds.github.io/nbdoc-docusaurus/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/outerbounds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-22T05:35:37.000Z","updated_at":"2025-03-24T14:00:08.000Z","dependencies_parsed_at":"2022-07-19T22:18:05.870Z","dependency_job_id":null,"html_url":"https://github.com/outerbounds/nbdoc-docusaurus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outerbounds%2Fnbdoc-docusaurus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outerbounds%2Fnbdoc-docusaurus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outerbounds%2Fnbdoc-docusaurus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outerbounds%2Fnbdoc-docusaurus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/outerbounds","download_url":"https://codeload.github.com/outerbounds/nbdoc-docusaurus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250328555,"owners_count":21412635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:52.838Z","updated_at":"2025-04-22T21:31:54.185Z","avatar_url":"https://github.com/outerbounds.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![Deploy to GitHub Pages](https://github.com/outerbounds/nbdoc-docusaurus/actions/workflows/deploy.yml/badge.svg)](https://github.com/outerbounds/nbdoc-docusaurus/actions/workflows/deploy.yml) [![](https://img.shields.io/static/v1?label=fastai\u0026message=nbdev\u0026color=57aeac\u0026labelColor=black\u0026style=flat\u0026logo=data:image/png;base64,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)](https://github.com/fastai/nbdev)\n\n# Create Testable, Reproduceable Docs and Blogs With Notebooks\n\n\u003e Never copy and paste code into documentation again!\n\n👉 [See a live example](https://outerbounds.github.io/nbdoc-docusaurus/docs/nb) of a post made with notebooks 🌐 🚀\n\n\u003ca id=\"markdown-background\" name=\"background\"\u003e\u003c/a\u003e\n\n## Background\n\nThis repo provides an example of how to create blog posts and/or documentation with [Docusaurus](https://docusaurus.io/) using Jupyter Notebooks.  When you create documentation with notebooks:\n\n- Your **documentation is fully testable** with unit tests\n- **No more copy / pasting code** into your blog posts and docs\n- **The output of code is always up to date**, since it is generated by actually running  code, rather than copying and pasting it from somewhere else.\n- You can **author technical posts and docs in a WYSIWYG manner**, which allows you to iterate faster.\n- You can still write markdown posts if you want to.\n\n\n\u003c!-- TOC --\u003e\n\n- [Background](#background)\n- [Getting Started](#getting-started)\n    - [1. Fork this repo](#1-fork-this-repo)\n    - [2. Edit `settings.ini`](#2-edit-settingsini)\n    - [3. Install Dependencies](#3-install-dependencies)\n- [Using Notebooks](#using-notebooks)\n    - [Notebook Development Setup](#notebook-development-setup)\n    - [Tutorial](#tutorial)\n        - [Running Tests \u0026 Updating Notebooks](#running-tests--updating-notebooks)\n        - [Skipping tests in cells](#skipping-tests-in-cells)\n        - [Update all notebooks](#update-all-notebooks)\n        - [Ignoring Skip Flags](#ignoring-skip-flags)\n    - [Hotkeys For Jupyter](#hotkeys-for-jupyter)\n- [Using Markdown](#using-markdown)\n- [Running the documentation locally](#running-the-documentation-locally)\n- [Automatic publishing](#automatic-publishing)\n- [About](#about)\n\n\u003c!-- /TOC --\u003e\n\n\n\u003ca id=\"markdown-getting-started\" name=\"getting-started\"\u003e\u003c/a\u003e\n\n## Getting Started\n\nThis project assumes some familiarity with static site generators.  It is also very helpful to gain some familiarity with [Docusaurus](https://docusaurus.io/) and it's general features.\n\n\u003ca id=\"markdown-1-fork-this-repo\" name=\"1-fork-this-repo\"\u003e\u003c/a\u003e\n\n### 1. Fork this repo\n\nTo create your own blog or docs site, you can start by forking this repo, or creating a new repo by using this one as a [repository template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository).\n\nThis repo has both blog and docs, but you might want to enable [blog only mode](https://docusaurus.io/docs/blog#blog-only-mode) or [docs only mode](https://docusaurus.io/docs/docs-introduction#docs-only-mode)\n\n\n\u003ca id=\"markdown-2-edit-settingsini\" name=\"2-edit-settingsini\"\u003e\u003c/a\u003e\n\n### 2. Edit `settings.ini`\n\nAfter that, you should change the follwing lines in the [settings.ini](settings.ini) file.  The keys are described below:\n\n```diff\n[DEFAULT]\nnbs_path = .\nrecursive = True\ntst_flags = notest\n-user = outerbounds\n+user = \u003cyour github username\u003e\n-doc_host = https://outerbounds.github.io\n+doc_host = https://\u003cyour github user name\u003e.github.io or your custom domain\n-doc_baseurl = /nbdoc-docusaurus\n+doc_baseurl = /\u003cname of your repo\u003e or path\n-module_baseurls = metaflow=https://github.com/Netflix/metaflow/tree/master/\n+module_baseurls = \u003cyour python module\u003e=https://github.com/a/path/tree/master/\n```\n\nThe definintions of these fields are as follows:\n\n- **`nbs_path`:** the top most in your directory that contains notebooks to be converted to markdown files.  The default value for this `.`, which just means the root of the repo.\n- **`recursive`:** set to `True` if you want to recurisvely find all notebooks under `nbs_path`, and `False` otherwise.  Defaults to `True`\n- **`tst_flags`:** special cell comment that will allow yout skip cell execution and test.  For example, adding the comment `#notest` in a code cell would result skip cell execution for that cell.  You can add mulitple values in this field seperated by a pipe `|`\n- **`doc_host`:** this is the domain where your docs are served. If your docs are served on GitHub Pages, this is typically `your-username.github.io`\n- **`doc_baseurl`:** the path on your domain that has the docs.  This is usually the root `/` so doesn't normally need to be changed.\n- **`module_baseurl`:** This is optional for a situations where you want to document python apis.  This allows documentation to include links to source code.\n\n\u003ca id=\"markdown-3-install-dependencies\" name=\"3-install-dependencies\"\u003e\u003c/a\u003e\n\n### 3. Install Dependencies\n\n1. Before you get started, you need to make sure you have [node and npm installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). \n\n2. Next, create an isolated python environment using your favorite tool such as `conda`, `pipenv`, `poetry` etc.  Then, from the root of this repo run this command in the terminal:\n\n    ```sh\n    make install\n    ```\n\nNote that this references `requirements.txt`, which you will have to update appropriately anytime you include addtional python dependencies in your documentation.\n\n\n\u003ca id=\"markdown-using-notebooks\" name=\"using-notebooks\"\u003e\u003c/a\u003e\n\n## Using Notebooks\n\n\n\n\u003ca id=\"markdown-notebook-development-setup\" name=\"notebook-development-setup\"\u003e\u003c/a\u003e\n\n### Notebook Development Setup\n\n1. You need to open 3 different terminal windows (I recommend using split panes), and run the following commands in three seperate windows:\n\n    _Note: we tried to use docker-compose but had trouble getting some things to run on Apple Silicon, so this will have to do for now._\n\n    Start the docs server:\n    \n    ```sh\n    make docs\n    ```\n\n    Watch for changes to notebooks:\n    \n    ```sh\n    make watch\n    ```\n\n    Start Jupyter Lab:\n    \n    ```sh\n    make nb\n    ```\n\n2. Open a browser window for the [authoring guide in the docs](http://localhost:3000/docs/nb).  You may have to hard-refresh the first time you make a change, but hot-reloading generally works.\n\n\n\u003ca id=\"markdown-tutorial\" name=\"tutorial\"\u003e\u003c/a\u003e\n\n### Tutorial\n\nTo go through the tutorial, open the [rendered authoring guide](http://localhost:3000/docs/nb) in one window, and the notebook [docs/nb.ipynb](docs/nb.ipynb) in another window.  Study the notebook cells and the corresponding rendered page carefully.  You will see many options for:\n\n- How to deal with scripts vs interactive code cells\n- How to run bash commands / scripts\n- How to setup front matter for page configuration\n- Hiding/Showing cell inputs, outputs or both\n- Selectively displaying Metaflow logs\n- How to setup tests\n- How to Author API docs\n\nAfter you complete the tutorial, you should run through this list and make sure you know how to do all of the above tasks.\n\n\u003ca id=\"markdown-running-tests--updating-notebooks\" name=\"running-tests--updating-notebooks\"\u003e\u003c/a\u003e\n\n#### Running Tests \u0026 Updating Notebooks\n\n\u003e To test the notebooks, run `make test` from the root of this repo.  This will execute all notebooks in parallel and report an error if there are any errors found.\n\n\u003ca id=\"markdown-skipping-tests-in-cells\" name=\"skipping-tests-in-cells\"\u003e\u003c/a\u003e\n\n#### Skipping tests in cells\n\n\u003e If you want to skip certain cells from running in tests because they take a really long time, you can place the comment `#notest` at the top of the cell.  You can add additional flags by adding pipe-delimited values into the `tst_flags` field of [settings.ini](settings.ini).\n\n\n\u003ca id=\"markdown-update-all-notebooks\" name=\"update-all-notebooks\"\u003e\u003c/a\u003e\n\n#### Update all notebooks\n\n\u003e You can refresh all notebooks in place with `make update`.  This runs all notebooks programatically, skipping over cells with `#notest` (or other `tst_flags` flags you set) and **saves the result to the same filename.**  This will also re-generate the markdown files from the updated notebooks.\n\n\u003e The reason for providing `make update` seperately from `make test` is so you can have the option of first testing your notebooks without overwriting them.\n\n\u003ca id=\"markdown-ignoring-skip-flags\" name=\"ignoring-skip-flags\"\u003e\u003c/a\u003e\n\n#### Ignoring Skip Flags\n\n\u003e We have previously discussed that you can skip tests or notebook refreshes in specific cells with the flag `#notest` (or other flags you set in [settings.ini](settings.ini)).  You can force these cells to be run or refreshed with the `--flags` argument.  For example, let's say we want to run tests or refresh notebooks and do not want to ignore cells with the `#notest` flag:\n\n- For testing: `nboc_test --flags #notest`\n- For refreshing notebooks: `nbdoc_update --flags #notest`\n\n\n\u003ca id=\"markdown-hotkeys-for-jupyter\" name=\"hotkeys-for-jupyter\"\u003e\u003c/a\u003e\n\n### Hotkeys For Jupyter\n\n\u003e People complain about \"state\" in Jupyter.  This can be easily avoided by frequently restarting the kernel and running all cells from the top.  Thankfully, you can set a hotkey that allows you to do this effortlessly.  In Jupyter Lab, go to `Settings` then `Advanced Settings Editor`.  Copy and paste the below json into the `User Prefences` pane.  If you already have user-defined shortcuts, modify this appropriately.\n\n```\n{\n\"shortcuts\": [\n    {\n        \"command\": \"notebook:restart-run-all\",\n        \"keys\": [\n            \"Ctrl R\",\n            \"R\"\n        ],\n        \"selector\": \"body\",\n    },\n    {\n        \"command\": \"notebook:restart-and-run-to-selected\",\n        \"keys\": [\n            \"Ctrl R\",\n            \"S\"\n        ],\n        \"selector\": \"body\",\n    },\n...\n}\n```\n\n\u003ca id=\"markdown-using-markdown\" name=\"using-markdown\"\u003e\u003c/a\u003e\n\n## Using Markdown\n\n\u003e You do not have to use notebooks to update documentation.  You can use markdown as you would normally do with Docusaurus.  This is a good option when there isn't much code in the document you are trying to write.\n\n\n\u003ca id=\"markdown-running-the-documentation-locally\" name=\"running-the-documentation-locally\"\u003e\u003c/a\u003e\n\n## Running the documentation locally\n\n* Clone this repo\n* `cd nbdoc-docusarus`\n* `make install`\n* `make docs`\n\n\u003e Any saved changes that you make to the `.md` files in the `docs` or `blogs` directory will automatically be reflected at [the local preview page](http://localhost:3000/).\n\n\n\u003ca id=\"markdown-automatic-publishing\" name=\"automatic-publishing\"\u003e\u003c/a\u003e\n\n## Automatic publishing\n\n\u003e Any pushes to the `master` branch will automatically publish to [the live documentation pages](https://outerbounds.github.io/docs/) . The publishing uses GitHub Actions and Github pages. You can see the progress of the publish action by going to the `Actions` tab of this repository.\n\n\n\u003ca id=\"markdown-about\" name=\"about\"\u003e\u003c/a\u003e\n\n## About\n\nWe use [nbdoc](https://github.com/outerbounds/nbdoc) as a notebook converter and testing utility, as well as [docusaurus](https://github.com/facebook/docusaurus) for the static site generator.  This technology is built using [nbdev](https://github.com/fastai/nbdev), a literate programming system.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fouterbounds%2Fnbdoc-docusaurus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fouterbounds%2Fnbdoc-docusaurus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fouterbounds%2Fnbdoc-docusaurus/lists"}