Merge branch 'master' into pr-150

Author: hoetmaaiers

.circleci/config.yml

@@ -17,7 +17,7 @@ jobs:
             - cache-pip
       # Install the packages needed to build our documentation
       # This will depend on your particular package!
-      - run: 
+      - run:
           name: Set up environment
           command: |
             # Install conda
@@ -41,8 +41,8 @@ jobs:
           name: Build docs to store
           command: |
             export PATH="$HOME/miniconda/bin:$PATH"
-            cd docs
-            make html
+            sphinx-build -b html docs/ docs/_build/html -W --keep-going
+
       # Tell Circle to store the documentation output in a folder that we can access later
       - store_artifacts:
           path: docs/_build/html/

.github/workflows/main.yml renamed to .github/workflows/artifact.yml

@@ -0,0 +1,64 @@
+name: continuous-integration
+
+on: [push, pull_request]
+
+jobs:
+
+  lint:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Set up Node/yarn
+      uses: actions/setup-node@v1
+      with:
+        node-version: '10.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade pre-commit
+        pip install -e .
+        yarn install
+
+    - name: Lint
+      run: |
+        pre-commit run --all-files
+
+
+  # Build docs on a number of Python versions. In the future this can be
+  # where tests go.
+  tests:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install -r docs/requirements.txt
+
+    # Build the docs
+    - name: Build docs to store
+      run: |
+        export PATH="$HOME/miniconda/bin:$PATH"
+        sphinx-build -b html docs/ docs/_build/html -W --keep-going

.github/workflows/tests.yml

@@ -101,4 +101,5 @@ ENV/
 # mypy
 .mypy_cache/
 
-node_modules/
+node_modules/
+.vscode

.gitignore

@@ -6,3 +6,12 @@ repos:
         language: system
         entry: bash -c "yarn build:production"
         files: ^src/*
+-   repo: https://github.com/psf/black
+    rev: stable
+    hooks:
+    -   id: black
+        language_version: python3.6
+-   repo: https://gitlab.com/pycqa/flake8
+    rev: 3.7.9
+    hooks:
+    -   id: flake8

.pre-commit-config.yaml

@@ -15,26 +15,18 @@ Sites that are using this theme:
 - JupyterHub and Binder: https://docs.mybinder.org/, http://z2jh.jupyter.org/en/latest/, https://repo2docker.readthedocs.io/en/latest/, https://jupyterhub-team-compass.readthedocs.io/en/latest/
 - Jupyter Book beta version uses an extension of this theme: https://beta.jupyterbook.org
 
-This repo holds a temporary (slimmed down) copy of the pandas documentation to
-test the theme with on PRs. The result is hosted at the demo site.
 
 ## Installation and usage
 
-This theme is not yet released as a package on PyPI, but you can already install
+The theme is available on PyPI and conda-forge. You can install
 and use as follows:
 
-- Install the `pydata-sphinx-theme` in your doc build environment from the git
-  repo. You can do this manually with pip:
+- Install the `pydata-sphinx-theme` in your doc build environment:
 
   ```
-  pip install git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master
-  ```
-
-  or in a conda environment yml file, you can add:
-
-  ```
-  - pip:
-    - git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master
+  pip install pydata-sphinx-theme
+  # or
+  conda install pydata-sphinx-theme --channel conda-forge
   ```
 
 - Then, in the `conf.py` of your sphinx docs, you update the `html_theme`
@@ -53,69 +45,11 @@ are very welcome!
 
 ## Theme development
 
-The theme is bundled via Webpack. In `./src/*` the theme related stylesheets and javascript is located. 2 entrypoints are available:
-
-- Stylesheet: `./src/scss/index.scss'
-- Javascript: `./src/js/index.js`
-
-Both entrypoints will be bundled into `./pydata_sphinx_theme/static/{css,js}`.
-
-Theme development was inspired by the [ReadTheDocs sphinx theme](https://github.com/readthedocs/sphinx_rtd_theme).
-
-### Steps to develop the theme:
-
-1. Install yarn
-2. Install theme dependencies
-3. Run development server
-4. Build production assets
-
-**Important:** in orde to commit changes to the theme, ensure you run `yarn build:production` so all assets will be bundled into `./pydata_sphinx_theme/static/`.
-
-#### Install yarn
-
-[Yarn](https://yarnpkg.com) is a package manager we use for managing Javascript and CSS dependencies.
-
-Install via conda:
+Contributions are very welcome! Installing the development version, building
+the demo docs and developing the css/js of the theme, etc, is explained in
+more detail in the contributing section of the documentation:
+https://pydata-sphinx-theme.readthedocs.io/en/latest/contributing.html
 
-```bash
-conda install yarn
-```
-
-Install alternative: https://classic.yarnpkg.com/en/docs/install.
-
-#### Install theme dependencies
-
-Install theme related dependencies:
-
-```bash
-yarn install
-```
-
-#### Run development server
-
-```bash
-yarn build:dev
-```
-
-A development server is available at http://localhost:1919. When working
-on the theme, like editing stylesheets, javascript, .rst or .py files
-every save reloads the development server. This reload includes bundling
-stylesheets, javascript, and running sphinx again.
-
-The following files will be watched and reloaded on change:
-
-- ./src/js/index.js
-- ./src/scss/index.scss
-- ./docs/\*\*/\*.rst
-- ./docs/\*\*/\*.py
-
-#### Build production assets
-
-To build the new theme assets into the theme, run the following command.
-
-```bash
-yarn build:production
-```
 
 ## How is this theme working?
 
@@ -152,13 +86,13 @@ To this end, this package includes:
   subclassing sphinx' translator, but overriding certain elements to generate
   Bootstrap-compatible html. Currently, this includes: converting admonitions to
   Bootstrap "alert" classes, and updating the classes used for html tables.
-- A [sphinx "monkeypatch"](./pydata_sphinx_theme/__init__.py) to add toctree
+- A [sphinx event](./pydata_sphinx_theme/__init__.py) to add navigation
   objects into the html context which is available in the html (jinja2)
   templates. This allows to put the structure of the navigation elements in the
   actual layout, instead of having to rely on the hard-coded formatting of
   sphinx (this is inspired on the navigation objects of mkdocs:
   https://www.mkdocs.org/user-guide/custom-themes/#nav). We would love to see
-  this added to sphinx itself (instead of needing to monkeypatch), but for not
+  this added to sphinx itself (instead of needing a sphinx event), but for now
   did not yet get any reaction from the sphinx developers.
 
 Those items also avoid writing javascript functions to "fix up" the html
@@ -173,3 +107,5 @@ Currently, the main difference is that this theme is using Bootstrap 4 instead
 of 3 and provides a different default layout. At some point, it would be good to
 contribute changes to that package (or at least the parts that deal with
 Bootstrap and sphinx that could be shared).
+
+The initial layout and css were inspired on the Bootstrap documentation site.

.vscode/settings.json

@@ -17,12 +17,12 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'PyData Sphinx Theme'
-copyright = '2019, PyData Community'
-author = 'PyData Community'
+project = "PyData Sphinx Theme"
+copyright = "2019, PyData Community"
+author = "PyData Community"
 
 # The full version, including alpha/beta/rc tags
-release = '0.0.1dev0'
+release = "0.0.1dev0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -42,28 +42,25 @@
 autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'pydata_sphinx_theme'
-html_logo = '_static/pandas.svg'
+html_theme = "pydata_sphinx_theme"
+html_logo = "_static/pandas.svg"
 
 html_theme_options = {
     "external_links": [
-        {
-            'url': "https://pandas.pydata.org/pandas-docs/stable/",
-            "name": "Pandas Docs"
-        }
+        {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"}
     ],
     "github_url": "https://github.com/pandas-dev/pydata-sphinx-theme",
     "twitter_url": "https://twitter.com/pandas_dev",
@@ -84,12 +81,13 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 
 # -- Auto-convert markdown pages to demo --------------------------------------
 import recommonmark
 from recommonmark.transform import AutoStructify
 
+
 def setup(app):
     app.add_transform(AutoStructify)

README.md

@@ -22,13 +22,91 @@ To install, you can run this from the root of the repo::
 Building the demo docs
 ======================
 
-Navigate to the `docs/` directory, and then run::
+For the tradiditional sphinx-way to build the demo site, navigate to the
+`docs/` directory, and then run::
 
     make html
 
 This will trigger sphinx to build the html version of the site. The output can
 be found in the ``docs/_build/html`` directory.
 
+However, when you want to edit the css/js sources, those need to be bundled
+and the workflow for this is explained in the next section.
+
+Theme development
+=================
+
+The css and javascript part of this theme is bundled via Webpack. In ``./src/*``
+the theme related stylesheets and javascript is located. 2 entrypoints are
+available:
+
+- Stylesheet: ``./src/scss/index.scss``
+- Javascript: ``./src/js/index.js``
+
+Both entrypoints will be bundled into ``./pydata_sphinx_theme/static/{css,js}``.
+
+Theme development was inspired by the `ReadTheDocs sphinx theme <https://github.com/readthedocs/sphinx_rtd_theme>`__.
+
+Steps to develop the theme
+--------------------------
+
+1. Install yarn
+2. Install theme dependencies
+3. Run development server
+4. Build production assets
+
+**Important:** in order to commit changes to the theme, ensure you run
+``yarn build:production`` so all assets will be bundled into
+``./pydata_sphinx_theme/static/``.
+
+Install yarn
+^^^^^^^^^^^^
+
+`Yarn <https://yarnpkg.com>`__ is a package manager we use for managing
+Javascript and CSS dependencies.
+
+Install via conda::
+
+    conda install yarn
+
+Install alternative: https://classic.yarnpkg.com/en/docs/install.
+
+Install theme dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Install theme related dependencies::
+
+    yarn install
+
+
+Run development server
+^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    yarn build:dev
+
+A development server is available at http://localhost:1919. When working
+on the theme, like editing stylesheets, javascript, .rst or .py files
+every save reloads the development server. This reload includes bundling
+stylesheets, javascript, and running sphinx again.
+
+The following files will be watched and reloaded on change:
+
+- ./src/js/index.js
+- ./src/scss/index.scss
+- ./docs/\*\*/\*.rst
+- ./docs/\*\*/\*.py
+
+Build production assets
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To build the new theme assets into the theme, run the following command.
+
+::
+
+    yarn build:production
+
 
 Contributing changes
 ====================