Merge pull request jupyterlab#157 from afshin/sphinx

Add Sphinx Documentation

.github/workflows/tests.yml

@@ -21,7 +21,7 @@ jobs:
         id: yarn-cache-dir-path
         run: echo "::set-output name=dir::$(yarn cache dir)"
       - name: Cache yarn
-        uses: actions/cache@v1
+        uses: actions/cache@v2
         id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
         with:
           path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
@@ -52,5 +52,6 @@ jobs:
             yarn test
 
       - name: Docs
+        if: ${{ matrix.os == 'ubuntu-latest' }}
         run: |
           yarn docs

.gitignore

@@ -9,6 +9,12 @@ build
 review/api/temp
 *.tsbuildinfo
 
+# copied changelog file
+docs/source/changelog.md
+
+# generated api files
+docs/api
+
 # jetbrains ide stuff
 *.iml
 .idea/
@@ -17,4 +23,3 @@ review/api/temp
 *.code-workspace
 .history
 .vscode
-

.readthedocs.yaml

@@ -0,0 +1,5 @@
+version: 2
+sphinx:
+  configuration: docs/source/conf.py
+conda:
+  environment: docs/environment.yml

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/environment.yml

@@ -0,0 +1,17 @@
+
+name: lumino_documentation
+channels:
+  - conda-forge
+dependencies:
+- python=3.8
+- sphinx>=1.8
+- sphinx-copybutton
+- sphinx_rtd_theme
+- pytest
+- pip
+- nodejs
+- pip:
+  - jsx-lexer
+  - pytest-check-links[cache]>=0.4.3
+  - myst_parser
+  - requests_cache

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_static/css/custom.css

@@ -0,0 +1,64 @@
+h4 {
+  font-size: 100%;
+}
+
+.wy-nav-side p.caption {
+  color: #f5f5f5;
+}
+
+div.wy-side-nav-search {
+  background: #f37626;
+}
+
+.wy-nav-content iframe {
+  margin: auto;
+  display: block;
+}
+
+.wy-breadcrumbs-aside img {
+  height: 1em !important;
+}
+
+/* Elevation
+  *
+  * We style box-shadows using Material Design's idea of elevation. These particular numbers are taken from here:
+  *
+  * https://github.com/material-components/material-components-web
+  * https://material-components-web.appspot.com/elevation.html
+  */
+
+.rst-content img.jp-screenshot {
+  border: none;
+  /* MD Elevation 8 */
+  box-shadow: 0px 5px 5px -3px rgba(0, 0, 0, 0.2),
+    0px 8px 10px 1px rgba(145, 145, 145, 0.14),
+    0px 3px 14px 2px rgba(0, 0, 0, 0.12);
+  margin-bottom: 24px;
+}
+
+/* 
+ * The div.jp-youtube-video styling is done to get the YouTube video to size dynamically
+ * to 100% of the content width.
+ */
+
+.rst-content div.jp-youtube-video {
+  position: relative;
+  width: 100%;
+  height: 0px;
+  /* This must be equal to the inverse of the aspect ratio of the video */
+  /* The current value is: 56.25% = 315/560 */
+  padding-bottom: 56.25%;
+  border: none;
+  /* MD Elevation 8 */
+  box-shadow: 0px 5px 5px -3px rgba(0, 0, 0, 0.2),
+    0px 8px 10px 1px rgba(0, 0, 0, 0.14), 0px 3px 14px 2px rgba(0, 0, 0, 0.12);
+  margin-bottom: 24px;
+}
+
+.rst-content div.jp-youtube-video iframe {
+  position: absolute;
+  left: 0px;
+  top: 0px;
+  width: 100%;
+  height: 100%;
+}

docs/source/_templates/breadcrumbs.html

@@ -0,0 +1,49 @@
+{% extends '!breadcrumbs.html' %}
+
+{% block breadcrumbs %}
+  <li><a href="{{ pathto(master_doc) }}">{{ _('Docs') }}</a> &raquo;</li>
+    {% for doc in parents %}
+      <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+    {% endfor %}
+  <li>{{ title }}</li>
+{% endblock %}
+  {% block breadcrumbs_aside %}
+    <li class="wy-breadcrumbs-aside">
+    {% if hasdoc(pagename) %}
+      {% if display_github %}
+      {% if check_meta and 'github_url' in meta %}
+        <!-- User defined GitHub URL -->
+        <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+      {% else %}
+        <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode or "blob" }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+      {% endif %}
+      {% elif display_bitbucket %}
+      {% if check_meta and 'bitbucket_url' in meta %}
+        <!-- User defined Bitbucket URL -->
+        <a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+      {% else %}
+        <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ suffix }}?mode={{ theme_vcs_pageview_mode or "view" }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+      {% endif %}
+      {% elif display_gitlab %}
+      {% if check_meta and 'gitlab_url' in meta %}
+        <!-- User defined GitLab URL -->
+        <a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+      {% else %}
+        <a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode or "blob" }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+      {% endif %}
+      {% elif show_source and source_url_prefix %}
+      <a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>
+      {% elif show_source and has_source and sourcename %}
+      <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+      {% endif %}
+    {% endif %}
+    </li>
+    <li class="wy-breadcrumbs-aside">
+      <a href="https://jupyter.org/documentation">
+        <img src="{{ pathto('_static/jupyter_logo.svg', 1) }}"></img>
+        {{ _('Jupyter') }}
+      </a>
+      &vert;
+      &nbsp;
+    </li>
+{% endblock %}

docs/source/_templates/footer.html

@@ -0,0 +1,54 @@
+<footer>
+  {% if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
+      {% if next %}
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n" rel="next">{{ _('Next') }} <span class="fa fa-arrow-circle-right"></span></a>
+      {% endif %}
+      {% if prev %}
+        <a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> {{ _('Previous') }}</a>
+      {% endif %}
+    </div>
+  {% endif %}
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>
+    {%- if show_copyright %}
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.<br/>
+        The Jupyter Trademark is registered with the U.S. Patent &amp Trademark Office.
+        {% endtrans %}
+      {%- endif %}
+    {%- endif %}
+
+    {%- if build_id and build_url %}
+      {% trans build_url=build_url, build_id=build_id %}
+        <span class="build">
+          Build
+          <a href="{{ build_url }}">{{ build_id }}</a>.
+        </span>
+      {% endtrans %}
+    {%- elif commit %}
+      {% trans commit=commit %}
+        <span class="commit">
+          Revision <code>{{ commit }}</code>.
+        </span>
+      {% endtrans %}
+    {%- elif last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    {%- endif %}
+
+    </p>
+  </div>
+
+  {%- if show_sphinx %}
+  {% trans %}Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}.
+  {%- endif %}
+
+  {%- block extrafooter %} {% endblock %}
+
+</footer>
+

docs/source/api.rst

@@ -0,0 +1,11 @@
+Lumino API Reference
+========================
+
+.. this doc exists as a resolvable link target
+.. which statically included files are not
+
+.. meta::
+    :http-equiv=refresh: 0;url=./api/index.html
+
+The Lumino API reference docs are `here <./api/index.html>`_
+if you are not redirected automatically.