Skip to content

Commit 1a96816

Browse files
afshinafshin
authored
Add Sphinx docs (#169)
1 parent a82794a commit 1a96816

File tree

12 files changed

+256
-16
lines changed

12 files changed

+256
-16
lines changed

‎.github/workflows/tests.yml‎

Lines changed: 36 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ name: Tests
22

33
on: [push, pull_request]
44

5+
defaults:
6+
run:
7+
shell: bash -l {0}
8+
59
jobs:
610
linux:
711
name: ${{ matrix.PLATFORM }} py${{ matrix.PYTHON_VERSION }}
@@ -20,28 +24,37 @@ jobs:
2024
PYTHON_VERSION: pypy3
2125
steps:
2226
- name: Checkout
23-
uses: actions/checkout@v1
27+
uses: actions/checkout@v2
2428
- name: Cache pip
25-
uses: actions/cache@v1
29+
uses: actions/cache@v2
2630
with:
2731
path: ~/.cache/pip
2832
key: ${{ runner.os }}-py-${{ matrix.PYTHON_VERSION }}-pip-${{ hashFiles('**/setup.py') }}
29-
- name: Setup python ${{ matrix.PYTHON_VERSION }}
30-
uses: actions/setup-python@v1
33+
- name: Cache conda
34+
uses: actions/cache@v2
35+
with:
36+
path: ~/conda_pkgs_dir
37+
key:
38+
${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
39+
hashFiles('etc/example-environment.yml') }}
40+
- name: Setup conda ${{ matrix.PYTHON_VERSION }}
41+
uses: conda-incubator/setup-miniconda@v2
3142
with:
32-
python-version: ${{ matrix.PYTHON_VERSION }}
33-
architecture: 'x64'
43+
auto-update-conda: true
44+
python-version: ${{ matrix.python-version }}
3445
- name: Install python dependencies
3546
run: |
36-
pip install setuptools pip wheel --upgrade --user --cache-dir ~/.cache/pip
47+
conda install setuptools pip wheel
48+
- name: Install pywin32 on Windows
49+
if: ${{ runner.os == 'Windows' }}
50+
run: conda install pywin32
3751
- name: Install project dependencies
3852
run: |
3953
pip install -v -e ".[test]" --cache-dir ~/.cache/pip
40-
- name: Show python environment
41-
run: |
42-
python --version
43-
python -m pip freeze
44-
python -m pip check
54+
- run: conda info
55+
- run: conda list
56+
- run: conda config --show
57+
- run: pip check
4558
- name: Run python tests
4659
# See `setup.cfg` for full test options
4760
run: |
@@ -52,8 +65,18 @@ jobs:
5265
- name: Install and Test SDist
5366
if: ${{ runner.os != 'Windows' }}
5467
run: |
68+
set -eux
5569
pip uninstall -y jupyterlab_server
5670
python setup.py sdist
5771
cd dist
5872
pip install *.tar.gz
59-
pytest --pyargs jupyterlab_server
73+
pytest --pyargs jupyterlab_server
74+
- name: Build docs
75+
run: |
76+
set -eux
77+
pushd docs
78+
conda env create -f environment.yml
79+
conda activate jupyterlab_server_documentation
80+
make html
81+
conda deactivate
82+
popd

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,6 @@ __pycache__
1717
.coverage
1818
.cache
1919
.pytest_cache
20+
21+
# generated changelog
22+
docs/source/changelog.md

‎CHANGELOG.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
github_url: 'https://github.com/jupyterlab/jupyterlab_server/blob/master/CHANGELOG.md'
3+
---
4+
15
# Change Log
26

37
## 2.3.0
@@ -284,4 +288,4 @@
284288

285289
## v0.2.0
286290

287-
* Clean up config handling [#3](https://github.com/jupyterlab/jupyterlab_server/pull/3) ([@blink1073](https://github.com/blink1073))
291+
* Clean up config handling [#3](https://github.com/jupyterlab/jupyterlab_server/pull/3) ([@blink1073](https://github.com/blink1073))

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/environment.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
name: jupyterlab_server_documentation
3+
channels:
4+
- conda-forge
5+
dependencies:
6+
- python=3.8
7+
- sphinx>=1.8
8+
- sphinx-copybutton
9+
- pip
10+
- myst-parser
11+
- pip:
12+
- autodoc-traits
13+
- pydata_sphinx_theme

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/api/app.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
=========================
2+
Application configuration
3+
=========================
4+
5+
Module: :mod:`jupyterlab_server.app`
6+
====================================
7+
8+
.. automodule:: jupyterlab_server.app
9+
10+
.. currentmodule:: jupyterlab_server.app
11+
12+
:class:`LabServerApp`
13+
---------------------
14+
15+
.. autoconfigurable:: LabServerApp

‎docs/source/api/index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---------------------
2+
JupyterLab Server API
3+
---------------------
4+
5+
JupyterLab Server API Reference:
6+
7+
.. toctree::
8+
app
9+

‎docs/source/conf.py‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
# import os
14+
# import sys
15+
# sys.path.insert(0, os.path.abspath('.'))
16+
import os.path as osp
17+
import shutil
18+
19+
HERE = osp.abspath(osp.dirname(__file__))
20+
21+
# -- Project information -----------------------------------------------------
22+
23+
project = 'JupyterLab Server'
24+
copyright = '2021, Project Jupyter'
25+
author = 'Project Jupyter'
26+
27+
# The full version, including alpha/beta/rc tags
28+
_version_py = osp.join(HERE, '..', '..', 'jupyterlab_server', '_version.py')
29+
version_ns = {}
30+
31+
with open(_version_py, mode='r') as version_file:
32+
exec(version_file.read(), version_ns)
33+
34+
# The short X.Y version.
35+
version = '%i.%i' % version_ns['version_info'][:2]
36+
# The full version, including alpha/beta/rc tags.
37+
release = version_ns['__version__']
38+
39+
40+
# -- General configuration ---------------------------------------------------
41+
42+
# Add any Sphinx extension module names here, as strings. They can be
43+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
44+
# ones.
45+
extensions = [
46+
'myst_parser',
47+
'autodoc_traits',
48+
'sphinx.ext.autodoc',
49+
'sphinx.ext.intersphinx',
50+
'sphinx.ext.mathjax',
51+
'sphinx_copybutton'
52+
]
53+
54+
myst_enable_extensions = ["html_image"]
55+
56+
# Add any paths that contain templates here, relative to this directory.
57+
templates_path = ['_templates']
58+
59+
# List of patterns, relative to source directory, that match files and
60+
# directories to ignore when looking for source files.
61+
# This pattern also affects html_static_path and html_extra_path.
62+
exclude_patterns = []
63+
64+
65+
# -- Options for HTML output -------------------------------------------------
66+
67+
# The theme to use for HTML and HTML Help pages. See the documentation for
68+
# a list of builtin themes.
69+
#
70+
#
71+
html_theme = "pydata_sphinx_theme"
72+
73+
# Add any paths that contain custom static files (such as style sheets) here,
74+
# relative to this directory. They are copied after the builtin static files,
75+
# so a file named "default.css" will overwrite the builtin "default.css".
76+
html_static_path = ['_static']
77+
78+
# Output for github to be used in links
79+
html_context = {
80+
"display_github": True, # Integrate GitHub
81+
"github_user": "jupyterlab", # Username
82+
"github_repo": "jupyterlab_server", # Repo name
83+
"github_version": "master", # Version
84+
"conf_py_path": "/docs/source/", # Path in the checkout to the docs root
85+
}
86+
87+
88+
def setup(app):
89+
dest = osp.join(HERE, 'changelog.md')
90+
shutil.copy(osp.join(HERE, '..', '..', 'CHANGELOG.md'), dest)

‎docs/source/index.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. jupyterlab_server documentation master file, created by
2+
sphinx-quickstart on Tue Mar 30 03:25:58 2021.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to JupyterLab Server's documentation!
7+
=============================================
8+
9+
.. toctree::
10+
:maxdepth: 1
11+
:caption: Contents:
12+
13+
changelog
14+
api/index
15+
16+
17+
Indices and tables
18+
==================
19+
20+
* :ref:`genindex`
21+
* :ref:`modindex`
22+
* :ref:`search`

0 commit comments

Comments
 (0)