Unverified Commit ab383767 authored by Jeremy Tuloup's avatar Jeremy Tuloup Committed by GitHub
Browse files

Merge pull request #64 from bollwyvl/add-docs-build

Add docs build for ReadTheDocs
parents d82efe30 26e30cae
# this is a minimal conda/mamba environment for working on JupyterLite and upstreams
name: jupyterlite-dev
# this is a conda/mamba environment for working on JupyterLite and upstreams
channels:
- conda-forge
dependencies:
- git
# demo stuff
- jupyter-server-proxy
- jupyterlab >=3,<4
- jupyterlab-classic
- nodejs >=12,!=13.*,<15
- git
### DOCS ENV ###
# runtimes
- nodejs >=14,<15
- python >=3.8,<3.9
# build
- doit >=0.33,<0.34
- flit >=3.1
- pip
- wheel
- yarn <2
# docs
- myst-nb
- pydata-sphinx-theme
- sphinx
### DOCS ENV ###
#!/usr/bin/env bash
set -eux
yarn
yarn build
doit build
# enable the proxy
for app in notebook server; do
......
......@@ -14,6 +14,7 @@ node_modules
coverage
*.map.js
*.bundle.js
docs/_build
# jetbrains IDE stuff
.idea/
......
......@@ -19,6 +19,9 @@ jobs:
uses: actions/setup-node@v2
with:
node-version: '14.x'
- uses: actions/setup-python@v2
with:
python-version: '3.8'
- name: Cache node modules
uses: actions/cache@v2
id: cache-node-modules
......@@ -36,17 +39,32 @@ jobs:
${{ env.CACHE_EPOCH }}-yarn-packages-${{ hashFiles('yarn.lock') }}
restore-keys: |
${{ env.CACHE_EPOCH }}-yarn-packages-
- uses: actions/cache@v2
with:
path: ~/.cache/pip
key: |
${{ env.CACHE_EPOCH }}-${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
restore-keys: |
${{ env.CACHE_EPOCH }}-${{ runner.os }}-pip-
- name: Setup
run: |
pip install -U pip setuptools
pip install -r requirements.txt
- name: Install
if: steps.cache-node-modules.outputs.cache-hit != 'true'
run: |
yarn --frozen-lockfile
doit setup:js
- name: Build
run: |
yarn build
doit build
- name: Upload (dist)
uses: actions/upload-artifact@v2
with:
name: jupyterlite dist ${{ github.run_number }}
path: ./dist
- name: Lint
run: |
yarn lint
doit lint
- name: Test
run: |
yarn build:test
yarn test
doit test
......@@ -123,6 +123,6 @@ app/test/data
# do not include kernels such as Pyodide
app/kernels
yarn-error.log
*.log
!packages/pyolite-kernel/py/dist/
.doit*
node_modules
**/node_modules
**/lib
**/node_modules
**/package.json
**/static
build
docs/_build
node_modules
version: 2
conda:
environment: docs/environment.yml
sphinx:
builder: html
configuration: docs/conf.py
fail_on_warning: true
# CHANGELOG
## jupyterlite 0.1.0
> TBD
# Contributing to JupyterLite
# Contributing
Thanks for contributing to JupyterLite!
......@@ -7,7 +7,7 @@ Thanks for contributing to JupyterLite!
## Setup
### Get the code
### Get the Code
```bash
git clone https://github.com/jtpio/jupyterlite
......@@ -22,6 +22,7 @@ You'll need:
- `git`
- `nodejs >=12`
- `yarn <2`
- `python >=3.8`
Various package managers on different operating systems provide these.
......@@ -35,8 +36,45 @@ Various package managers on different operating systems provide these.
## Development Tasks
### doit
[doit](https://github.com/pydoit/doit) handles the full software lifecycle, spanning
JavaScript to documentation building. It understands the dependencies between different
nested _tasks_, usually as files that change on disk.
#### List Tasks
To see all of the _tasks_ available, use the `list` action:
```bash
doit list --all --status
```
To get information about a specific _task_, use the info `info` _action_ with the _task_
name from the first column of `list`:
```bash
doit info build:js:app:classic
```
#### Task and Action Defaults
The default `doit` _action_ is `run` which... runs the named _tasks_.
The default tasks are `lint` and `build`, which do basically everything performed by
continuous integration, so the following are equivalent:
```bash
doit
doit lint build
doit run lint build
```
### JavaScript development
While most of the scripts below will be run (in the correct order based on changes) by
`doit`, the following _scripts_ (defined in `package.json`) are worth highlighting.
#### Quick start
Most of the [development tasks](#development-tasks) can be run with one command:
......@@ -45,13 +83,13 @@ Most of the [development tasks](#development-tasks) can be run with one command:
yarn bootstrap
```
#### Install
#### Install JavaScript Dependencies
```bash
yarn
```
#### Build
#### Build Apps
To build development assets:
......@@ -65,7 +103,7 @@ To build production assets:
yarn build:prod
```
#### Serve
#### Serve Apps
> These are **not real server solutions**, but they _will_ serve all of the assets types
> (including `.wasm`) correctly for JupyterLite under development, testing, and demo
......@@ -86,25 +124,43 @@ Python 3.7+):
yarn serve:py
```
#### Watch
#### Watch Sources
```bash
yarn watch
```
#### Lint
#### Lint/Format Sources
```bash
yarn lint
```
#### Test
#### Run Unit Tests
```bash
yarn build:test
yarn test
```
### Documentation
The documentation site, served on readthedocs.io, uses information from different parts
of the software lifecycle (e.g. contains a copy of the built `app` directory), so using
the [doit](#doit) tools are recommended.
#### Build Documentation
```bash
doit docs
```
#### Watch Documentation
```bash
doit watch:docs
```
## Community Tasks
### Issues
......@@ -130,7 +186,7 @@ JupyterLite become _real_ as [pull requests].
- Fork the repo
- Make a new branch off `main`
- Make changes
- Run the `lint` and `test`
- Run `doit lint test`
- Push to your fork
- Start the pull request
- your `git` cli should offer you a link, as will the GitHub web UI
......@@ -148,5 +204,5 @@ JupyterLite become _real_ as [pull requests].
[new issue]: https://github.com/jtpio/jupyterlite/issues/new
[pull requests]: https://github.com/jtpio/jupyterlite/pulls
[repo]: https://github.com/jtpio/jupyterlite
[coc]: (https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md)
[mambaforge]: https://github.com/conda-forge/miniforge/
[coc]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md
[mambaforge]: https://github.com/conda-forge/miniforge
# JupyterLite
[![ci-badge]][ci] [![binder-badge]][binder]
[![ci-badge]][ci] [![binder-badge]][binder] [![docs-badge]][docs]
[ci-badge]: https://github.com/jtpio/jupyterlite/workflows/Build/badge.svg
[ci]: https://github.com/jtpio/jupyterlite/actions?query=branch%3Amain
[binder-badge]: https://mybinder.org/badge_logo.svg
[binder]: https://mybinder.org/v2/gh/jtpio/jupyterlite/main?urlpath=lab
[docs-badge]: https://readthedocs.org/projects/jupyterlite/badge/?version=latest
[docs]: https://jupyterlite.readthedocs.io/en/latest/?badge=latest
JupyterLite is a JupyterLab distribution that **runs entirely in the browser** built
from the ground-up using JupyterLab components and plugins.
......
# Releasing JupyterLite
*/test/**
babel.config.*
jest-setup.js
jest.config.js
node_modules/
tsconfig.*
webpack.config.*
{
"name": "@jupyterlite/app",
"version": "0.1.0",
"homepage": "https://github.com/jtpio/jupyterlite",
"bugs": {
"url": "https://github.com/jtpio/jupyterlite/issues"
},
"repository": {
"type": "git",
"url": "https://github.com/jtpio/jupyterlite"
},
"license": "BSD-3-Clause",
"author": "JupyterLite Contributors"
}
:root {
--jp-orange: #f37726;
}
@media (min-width: 1200px) {
.container,
.container-xl {
max-width: 100%;
}
}
#navbar-start {
font-family: var(--pst-font-family-heading);
font-size: 1.6em;
}
@media (min-width: 960px) {
#navbar-center {
display: flex;
align-items: baseline;
}
}
.btn-warning {
background-color: var(--jp-orange);
color: #fff;
}
<strong>Try</strong>
<a
href="{{ pathto('_static/lab/index.html', 1) }}"
class="btn btn-warning"
target="_blank"
data-toggle="tooltip"
data-placement="bottom"
title="Try JupyterLab Lite"
>
<i class="fas fa-flask"></i>
Lab
</a>
<a
href="{{ pathto('_static/classic/index.html', 1) }}"
class="btn btn-warning"
target="_blank"
data-toggle="tooltip"
data-placement="bottom"
title="Try JupyterLab Classic Lite"
>
<i class="fas fa-book"></i>
Classic
</a>
<script>
$(function() {
$('[data-toggle="tooltip"]').tooltip();
});
</script>
<a class="navbar-brand" href="{{ pathto(master_doc) }}">
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo" />
<span class="title">{{ project }}</span>
</a>
```{include} ../CHANGELOG.md
```
"""documentation for jupyterlite"""
import os
import json
import datetime
from pathlib import Path
HERE = Path(__file__).parent
ROOT = HERE.parent
APP_PKG = ROOT / "app/package.json"
APP_DATA = json.loads(APP_PKG.read_text(encoding="utf-8"))
# metadata
author = APP_DATA["author"]
project = author.replace("Contributors", "").strip()
copyright = f"{datetime.date.today().year}, {author}"
# The full version, including alpha/beta/rc tags
release = APP_DATA["version"]
# The short X.Y version
version = ".".join(release.rsplit(".", 1))
# sphinx config
extensions = [
"sphinx.ext.autosectionlabel",
"myst_nb",
]
autosectionlabel_prefix_document = True
# files
templates_path = ["_templates"]
html_favicon = "../app/lab/favicon.ico"
html_static_path = ["_static", "../app"]
exclude_patterns = [
".ipynb_checkpoints",
"**/.ipynb_checkpoints",
"**/~.*",
"**/node_modules",
"babel.config.*",
"jest-setup.js",
"jest.config.js",
"test/",
"tsconfig.*",
"webpack.config.*",
]
html_css_files = [
"theme.css",
]
# theme
html_theme = "pydata_sphinx_theme"
html_logo = "_static/icon.svg"
html_theme_options = {
"github_url": APP_DATA["homepage"],
"use_edit_page_button": True,
"navbar_start": ["launch.html"],
"navbar_center": ["navbar-logo.html", "navbar-nav.html"],
}
html_context = {
"github_user": "jtpio",
"github_repo": "jupyterlite",
"github_version": "main",
"doc_path": "docs",
}
if os.environ.get("READTHEDOCS"):
import subprocess
subprocess.check_call(["doit", "build"], cwd=str(ROOT))
```{include} ../CONTRIBUTING.md
```
name: jupyterlite-docs
# this is a conda/mamba environment for building the JupyterLite documentation
channels:
- conda-forge
- nodefaults
dependencies:
### DOCS ENV ###
# runtimes
- nodejs >=14,<15
- python >=3.8,<3.9
# build
- doit >=0.33,<0.34
- flit >=3.1
- pip
- wheel
- yarn <2
# docs
- myst-nb
- pydata-sphinx-theme
- sphinx
### DOCS ENV ###
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment