From a238075ca1f1a66fc1f535a8c2b6e3f2c83f3ec9 Mon Sep 17 00:00:00 2001 From: Martin Larralde Date: Tue, 12 Nov 2019 11:43:19 +0100 Subject: [PATCH 01/39] Use `setup.cfg` for package distribution configuration --- setup.cfg | 38 ++++++++++++++++++++++++++++++ setup.py | 69 +++---------------------------------------------------- 2 files changed, 41 insertions(+), 66 deletions(-) create mode 100644 setup.cfg diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 00000000..0a3a016e --- /dev/null +++ b/setup.cfg @@ -0,0 +1,38 @@ +[metadata] +name = sphinx-bootstrap-theme +version = attr: sphinx_bootstrap_theme.__version__ +author = Ryan Roemer +author-email = ryan@loose-bits.com +home-page = http://ryan-roemer.github.com/sphinx-bootstrap-theme/README.html +description = Sphinx Bootstrap Theme. +long_description = file: README.rst +long_description_content_type = text/x-rst +keywords = sphinx, bootstrap, html, theme +classifiers = + Development Status :: 5 - Production/Stable + Environment :: Web Environment + Intended Audience :: Developers + Intended Audience :: System Administrators + License :: OSI Approved :: MIT License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Topic :: Internet + Topic :: Software Development :: Documentation + +[bdist_wheel] +universal = 1 + +[options] +zip_safe = false +include_package_data = true +packages = + sphinx_bootstrap_theme + sphinx_bootstrap_theme.bootstrap +setup_requires = + setuptools + +[options.entry_points] +sphinx.html_themes = + bootstrap = sphinx_bootstrap_theme diff --git a/setup.py b/setup.py index 90509cfa..6da9f3dc 100644 --- a/setup.py +++ b/setup.py @@ -1,72 +1,9 @@ """Sphinx Bootstrap Theme package.""" import os -from setuptools import setup, find_packages +import setuptools -from sphinx_bootstrap_theme import __version__ - -############################################################################### -# Environment and Packages. -############################################################################### # Don't copy Mac OS X resource forks on tar/gzip. os.environ['COPYFILE_DISABLE'] = "true" -# Packages. -MOD_NAME = "sphinx_bootstrap_theme" -PKGS = [x for x in find_packages() if x.split('.')[0] == MOD_NAME] - - -############################################################################### -# Helpers. -############################################################################### -def read_file(name): - """Read file name (without extension) to string.""" - cur_path = os.path.dirname(__file__) - exts = ('txt', 'rst') - for ext in exts: - path = os.path.join(cur_path, '.'.join((name, ext))) - if os.path.exists(path): - with open(path, 'rt') as file_obj: - return file_obj.read() - - return '' - - -############################################################################### -# Setup. -############################################################################### -setup( - name="sphinx-bootstrap-theme", - version=__version__, - use_2to3=True, - description="Sphinx Bootstrap Theme.", - long_description=read_file("README"), - url="http://ryan-roemer.github.com/sphinx-bootstrap-theme/README.html", - - author="Ryan Roemer", - author_email="ryan@loose-bits.com", - - classifiers=[ - "Development Status :: 5 - Production/Stable", - "Environment :: Web Environment", - "Intended Audience :: Developers", - "Intended Audience :: System Administrators", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", - "Programming Language :: Python", - "Programming Language :: Python :: 2", - "Programming Language :: Python :: 3", - "Topic :: Internet", - "Topic :: Software Development :: Documentation", - ], - - install_requires=[ - "setuptools", - ], - entry_points = { - 'sphinx.html_themes': [ - 'bootstrap = sphinx_bootstrap_theme', - ] - }, - packages=PKGS, - include_package_data=True, -) +# Setup the package. +setuptools.setup() From 89cd9cd38144dbc0f971ad6543fc819b6235c740 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Mon, 10 Feb 2020 23:01:33 -0500 Subject: [PATCH 02/39] add tox and github actions --- .github/workflows/tests.yaml | 69 +++++++++++++++ .gitignore | 135 +++++++++++++++++++++++++++++ demo/source/conf.py | 15 ++-- demo/source/downloads.rst | 9 -- demo/source/examples.rst | 12 +-- sphinx_bootstrap_theme/__init__.py | 2 + tox.ini | 67 ++++++++++++++ 7 files changed, 288 insertions(+), 21 deletions(-) create mode 100644 .github/workflows/tests.yaml delete mode 100644 demo/source/downloads.rst create mode 100644 tox.ini diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml new file mode 100644 index 00000000..2f3c296a --- /dev/null +++ b/.github/workflows/tests.yaml @@ -0,0 +1,69 @@ +name: Tests +on: [push] +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: 3.x + - name: Install Tox + run: pip install tox + - name: Lint + run: tox -e flake8 + dist: + name: Distribution Packaging + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: 3.x + - name: Install Tox + run: pip install tox + - name: Distribution Check + run: tox -e dist + docs: + name: Docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: 3.x + - name: Install Tox + run: pip install tox + - name: Build Docs + run: tox -e docs + test: + strategy: + matrix: + os: [macos-latest, windows-latest, ubuntu-latest] + python-version: [2.7, 3.5, 3.6, 3.7, 3.8] + name: Py ${{ matrix.python-version }} on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v2 + - name: Setup Python ${{ matrix.python-version }} + uses: actions/setup-python@v1 + with: + python-version: ${{ matrix.python-version }} + - name: Install Tox + run: pip install tox + - name: Test Sphinx 1.8.5 + env: + SPHINX_VERSION: ==1.8.5 + run: tox -e py + - name: Test Sphinx 2.0 + env: + SPHINX_VERSION: ==2.0 + run: tox -e py + if: matrix.python-version >= 3.5 + - name: Test Sphinx Latest + run: tox -e py + if: matrix.python-version >= 3.5 diff --git a/.gitignore b/.gitignore index 56c97ce5..4c8473f0 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,138 @@ __pycache__ .vscode Pipfile* +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + diff --git a/demo/source/conf.py b/demo/source/conf.py index 99c9883c..838e9351 100644 --- a/demo/source/conf.py +++ b/demo/source/conf.py @@ -16,8 +16,15 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -# Disabled: , 'sphinx.ext.intersphinx' -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.ifconfig', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode' +] + +intersphinx_mapping = {'python': ('http://docs.python.org/', None)} # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -302,7 +309,3 @@ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/demo/source/downloads.rst b/demo/source/downloads.rst deleted file mode 100644 index 4ada718c..00000000 --- a/demo/source/downloads.rst +++ /dev/null @@ -1,9 +0,0 @@ -=========== - Downloads -=========== - -The following zip bundles can be directly installed into your themes directory. -See the :doc:`README` page for zip bundle installation instructions. - -Versions -======== diff --git a/demo/source/examples.rst b/demo/source/examples.rst index fce41794..75d78d47 100644 --- a/demo/source/examples.rst +++ b/demo/source/examples.rst @@ -195,12 +195,12 @@ An example Python function. :param value: exception value :param tb: traceback object :param limit: maximum number of stack frames to show - :type limit: integer or None - :rtype: list of strings + :type limit: int or None + :rtype: list[str] -An example JavaScript function. +An example C++ function. -.. js:class:: MyAnimal(name[, age]) +.. cpp:function:: int foo(bool use_random = false) - :param string name: The name of the animal - :param number age: an optional age for the animal + :param use_random: Whether or not to return a random number. + :return: ``42`` if ``use_random == false``, a random number otherwise. diff --git a/sphinx_bootstrap_theme/__init__.py b/sphinx_bootstrap_theme/__init__.py index 70af13ee..af52ee4f 100644 --- a/sphinx_bootstrap_theme/__init__.py +++ b/sphinx_bootstrap_theme/__init__.py @@ -6,11 +6,13 @@ __version__ = ".".join(str(v) for v in VERSION) __version_full__ = __version__ + def get_html_theme_path(): """Return list of HTML theme paths.""" theme_path = os.path.abspath(os.path.dirname(__file__)) return [theme_path] + def setup(app): """Setup.""" # add_html_theme is new in Sphinx 1.6+ diff --git a/tox.ini b/tox.ini new file mode 100644 index 00000000..5a419576 --- /dev/null +++ b/tox.ini @@ -0,0 +1,67 @@ +[tox] +# By default, run tests and linting checks when invoking `tox`. +envlist = py, flake8 + +[testenv] +passenv = PYTHONWARNINGS +deps = + # NOTE: SPHINX_VERSION environment variable must have `==`, e.g.: + # SPHINX_VERSION="==1.8.5" tox + # On Unix, the double quotes are not necessary provided no spaces. + sphinx{env:SPHINX_VERSION:} +commands = + # TODO: create / add unit tests with pytest. + sphinx-build --version + +# Build demo site in nitpicky / warnings=error mode. +[testenv:docs] +changedir = demo +commands = + sphinx-build -W -n -b html -d {envtmpdir}/doctrees source {envtmpdir}/html + +# Open a development server. See options here: +# https://github.com/GaretJax/sphinx-autobuild +# +# Example run on port other than 8000: +# tox -e server -- -p 8080 +[testenv:server] +usedevelop = true +recreate = true +deps = + {[testenv]deps} + sphinx-autobuild +commands = + sphinx-autobuild -a -E \ + -b html \ + -d {envtmpdir}/doctrees \ + --watch {toxinidir}/sphinx_bootstrap_theme \ + {posargs} \ + {toxinidir}/demo/source \ + {envtmpdir}/html + +# Linting checks. +[testenv:flake8] +skip_install = true +deps = + flake8 +commands = + flake8 {posargs} setup.py sphinx_bootstrap_theme + +# Package for uploading to PyPI. Everything is put in dist/ folder. +[testenv:dist] +skip_install = true +deps = + readme_renderer + twine +commands = + {envpython} -c "import os.path as osp, sys; \ + dist_path = osp.join('{toxinidir}', 'dist'); \ + dist_exists = osp.exists(dist_path); \ + m = '[X] Delete the ' + dist_path + ' folder.\n' if dist_exists else ''; \ + sys.stderr.write(m); \ + sys.exit(int(dist_exists))" + {envpython} setup.py sdist + # TODO: this last one goes away once we ditch python 2 (via Sphinx 2.x+). + {envpython} setup.py bdist_wheel --universal + twine check dist/* + From e2857e3329187d2fb4810e38ad47af965d5b64df Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Tue, 11 Feb 2020 19:02:08 -0500 Subject: [PATCH 03/39] rename flake8 => lint (future linting tests) --- .github/workflows/tests.yaml | 2 +- tox.ini | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 2f3c296a..26f2ca75 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -13,7 +13,7 @@ jobs: - name: Install Tox run: pip install tox - name: Lint - run: tox -e flake8 + run: tox -e lint dist: name: Distribution Packaging runs-on: ubuntu-latest diff --git a/tox.ini b/tox.ini index 5a419576..dc531577 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] # By default, run tests and linting checks when invoking `tox`. -envlist = py, flake8 +envlist = py, lint [testenv] passenv = PYTHONWARNINGS @@ -40,7 +40,7 @@ commands = {envtmpdir}/html # Linting checks. -[testenv:flake8] +[testenv:lint] skip_install = true deps = flake8 From ab8ce52d00a3bc396eca770ab95b920a96630d0f Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Tue, 11 Feb 2020 21:06:57 -0500 Subject: [PATCH 04/39] add linkcheck tests, fix broken links --- .github/workflows/tests.yaml | 13 +++++++++++++ TODO.rst | 2 +- demo/source/examples.rst | 4 +++- tox.ini | 6 ++++++ 4 files changed, 23 insertions(+), 2 deletions(-) diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 26f2ca75..c14cb8da 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -40,6 +40,19 @@ jobs: run: pip install tox - name: Build Docs run: tox -e docs + linkcheck: + name: Linkcheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: 3.x + - name: Install Tox + run: pip install tox + - name: Build Linkcheck + run: tox -e linkcheck test: strategy: matrix: diff --git a/TODO.rst b/TODO.rst index d6ca90f5..a595619d 100644 --- a/TODO.rst +++ b/TODO.rst @@ -62,7 +62,7 @@ Updating Bootstrap 1. Get new ``bootstrap-VERSION`` and drop in ``bootstrap/static``. - - New versions should be available `here `_. + - New versions should be available `here `_. - Choose "Bootstrap": .. diff --git a/demo/source/examples.rst b/demo/source/examples.rst index 75d78d47..3b75cc8d 100644 --- a/demo/source/examples.rst +++ b/demo/source/examples.rst @@ -122,12 +122,14 @@ translates to a neat star: Tables ====== Here are some examples of Sphinx -`tables `_. The Sphinx Bootstrap +`tables `_. The Sphinx Bootstrap Theme removes all Sphinx ``docutils`` classes and replaces them with the default Bootstrap ``table`` class. You can add additional table classes using the Sphinx ``cssclass::`` directive, as demonstrated in the following tables. +.. _rst_tables: https://www.sphinx-doc.org/en/latest/usage/restructuredtext/basics.html#tables + Grid ---- A "**bordered**" grid table: diff --git a/tox.ini b/tox.ini index dc531577..5ddcaecd 100644 --- a/tox.ini +++ b/tox.ini @@ -19,6 +19,12 @@ changedir = demo commands = sphinx-build -W -n -b html -d {envtmpdir}/doctrees source {envtmpdir}/html +# Validate all links in the demo website. +[testenv:linkcheck] +changedir = demo +commands = + sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees source {envtmpdir}/linkcheck + # Open a development server. See options here: # https://github.com/GaretJax/sphinx-autobuild # From 502aae79310d7e25fefdbb5084338d466d4faa0b Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 06:01:36 -0500 Subject: [PATCH 05/39] {{test}} create packaging workflow, see what it does (we're gonna squash right?!) --- .github/workflows/package.yaml | 40 ++++++++++++++++++++++++++++++ .github/workflows/tests.yaml | 15 +---------- sphinx_bootstrap_theme/__init__.py | 8 ++++++ tox.ini | 3 +++ 4 files changed, 52 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/package.yaml diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml new file mode 100644 index 00000000..cc0a0a9e --- /dev/null +++ b/.github/workflows/package.yaml @@ -0,0 +1,40 @@ +name: Package +on: [push, pull_request] +jobs: + dist: + name: Distribution + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: 3.x + - name: Install Tox + run: pip install tox + # If the commit message contains [testpypi] then we will want to configure + # a "unique" dev version to package and later upload to Test PyPI, since + # we cannot upload the same __version__ more than once. In the + # sphinx_bootstrap_theme/__init__.py we allow the environment variable + # SPHINX_BOOTSTRAP_THEME_DEV_VERSION to be appended to the current version + # + # __version__ += "dev" + $SPHINX_BOOTSTRAP_THEME_DEV_VERSION + # + # To make this version unique, we simply use `date +%s` which gives the + # number of seconds since the Unix epoch. While other options exist, this + # is a simple way to create an increasing numerical "dev" version number. + - name: Configure Test PyPI Version + if: "contains(github.event.head_commit.message, '[testpypi]')" + # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env + run: echo "::set-env SPHINX_BOOTSTRAP_THEME_DEV_VERSION=$(date +%s)" + # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment + # variable may or may not be set. If not, just use __version__ unchanged. + - name: Package + run: tox -e dist + - name: Upload to Test PyPI + if: "contains(github.event.head_commit.message, '[testpypi]')" + uses: pypa/gh-action-pypi-publish@master + with: + user: __token__ + password: ${{ secrets.test_pypi_password }} + repository_url: https://test.pypi.org/legacy/ diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index c14cb8da..1a229699 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -1,5 +1,5 @@ name: Tests -on: [push] +on: [push, pull_request] jobs: lint: name: Lint @@ -14,19 +14,6 @@ jobs: run: pip install tox - name: Lint run: tox -e lint - dist: - name: Distribution Packaging - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: Setup Python - uses: actions/setup-python@v1 - with: - python-version: 3.x - - name: Install Tox - run: pip install tox - - name: Distribution Check - run: tox -e dist docs: name: Docs runs-on: ubuntu-latest diff --git a/sphinx_bootstrap_theme/__init__.py b/sphinx_bootstrap_theme/__init__.py index af52ee4f..239ca847 100644 --- a/sphinx_bootstrap_theme/__init__.py +++ b/sphinx_bootstrap_theme/__init__.py @@ -6,6 +6,14 @@ __version__ = ".".join(str(v) for v in VERSION) __version_full__ = __version__ +# NOTE: SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment variable is for internal +# usage only. It is used to create a dev release to deploy to TestPyPI, see +# .github/workflows/package.yaml for more information. +dev = os.getenv("SPHINX_BOOTSTRAP_THEME_DEV_VERSION", None) +if dev: + __version__ += ".dev" + dev + __version_full__ = __version__ + def get_html_theme_path(): """Return list of HTML theme paths.""" diff --git a/tox.ini b/tox.ini index 5ddcaecd..6bc25da0 100644 --- a/tox.ini +++ b/tox.ini @@ -55,6 +55,9 @@ commands = # Package for uploading to PyPI. Everything is put in dist/ folder. [testenv:dist] +passenv = + {[testenv]passenv} + SPHINX_BOOTSTRAP_THEME_DEV_VERSION skip_install = true deps = readme_renderer From 6a08e41df0e1084d9d2965181f4747768f4cb2ba Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 06:08:21 -0500 Subject: [PATCH 06/39] prevent double builds and [testpypi] deployment (!!!) --- .github/workflows/package.yaml | 8 +++++++- .github/workflows/tests.yaml | 8 +++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index cc0a0a9e..1df32b47 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -1,5 +1,11 @@ name: Package -on: [push, pull_request] +on: + push: + branches: + - master + pull_request: + branches: + - master jobs: dist: name: Distribution diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 1a229699..57f0cd06 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -1,5 +1,11 @@ name: Tests -on: [push, pull_request] +on: + push: + branches: + - master + pull_request: + branches: + - master jobs: lint: name: Lint From ea8772c8a6878242d05259179419f73ae3c6535e Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 06:19:20 -0500 Subject: [PATCH 07/39] [testpypi] attempt numbah 2 --- .github/workflows/package.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 1df32b47..356dedca 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -6,6 +6,7 @@ on: pull_request: branches: - master +# TODO: add tag here jobs: dist: name: Distribution @@ -18,6 +19,9 @@ jobs: python-version: 3.x - name: Install Tox run: pip install tox + - name: Extract Commit Message + # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env + run: echo "::set-env name=COMMIT_MESSAGE::$(git log -1 --pretty=%B)" # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the @@ -30,15 +34,15 @@ jobs: # number of seconds since the Unix epoch. While other options exist, this # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version - if: "contains(github.event.head_commit.message, '[testpypi]')" - # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env - run: echo "::set-env SPHINX_BOOTSTRAP_THEME_DEV_VERSION=$(date +%s)" + # TODO: we need to condition if NOT a tag + if: contains(env.COMMIT_MESSAGE, '[testpypi]') + run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment # variable may or may not be set. If not, just use __version__ unchanged. - name: Package run: tox -e dist - name: Upload to Test PyPI - if: "contains(github.event.head_commit.message, '[testpypi]')" + if: contains(env.COMMIT_MESSAGE, '[testpypi]') uses: pypa/gh-action-pypi-publish@master with: user: __token__ From dc99195d2cbdae765d17ad7129d921540c7016e5 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 07:23:56 -0500 Subject: [PATCH 08/39] debug [testpypi] --- .github/workflows/package.yaml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 356dedca..38766013 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -35,14 +35,21 @@ jobs: # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version # TODO: we need to condition if NOT a tag - if: contains(env.COMMIT_MESSAGE, '[testpypi]') + # if: contains(env.COMMIT_MESSAGE, '[testpypi]') run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" + - name: DEBUG + run: | + printenv + echo COMMIT_MESSAGE + echo $COMMIT_MESSAGE + echo SPHINX_BOOTSTRAP_THEME_DEV_VERSION + echo $SPHINX_BOOTSTRAP_THEME_DEV_VERSION # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment # variable may or may not be set. If not, just use __version__ unchanged. - name: Package run: tox -e dist - name: Upload to Test PyPI - if: contains(env.COMMIT_MESSAGE, '[testpypi]') + # if: contains(env.COMMIT_MESSAGE, '[testpypi]') uses: pypa/gh-action-pypi-publish@master with: user: __token__ From 304928509aae56a4324e80ec62adfdac45dfee4e Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 07:40:41 -0500 Subject: [PATCH 09/39] debug: improper token password, print more things ? log --- .github/workflows/package.yaml | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 38766013..be4fd3f3 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -38,12 +38,22 @@ jobs: # if: contains(env.COMMIT_MESSAGE, '[testpypi]') run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" - name: DEBUG + env: + GITHUB_CONTEXT: ${{ toJson(github) }} run: | + echo "$GITHUB_CONTEXT" printenv echo COMMIT_MESSAGE - echo $COMMIT_MESSAGE + echo "$COMMIT_MESSAGE" echo SPHINX_BOOTSTRAP_THEME_DEV_VERSION - echo $SPHINX_BOOTSTRAP_THEME_DEV_VERSION + echo "$SPHINX_BOOTSTRAP_THEME_DEV_VERSION" + echo "git log -1" + git log -1 + echo "git rev-parse HEAD" + git rev-parse HEAD + echo "GITHUB_SHA=$GITHUB_SHA" + echo "github.sha = ${{ github.sha }}" + echo "github.ref = ${{ github.ref }}" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment # variable may or may not be set. If not, just use __version__ unchanged. - name: Package @@ -53,5 +63,5 @@ jobs: uses: pypa/gh-action-pypi-publish@master with: user: __token__ - password: ${{ secrets.test_pypi_password }} + password: pypi-${{ secrets.test_pypi_password }} repository_url: https://test.pypi.org/legacy/ From 4ced5035056832a73ce701abecaa7ecc99e5267a Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 08:00:38 -0500 Subject: [PATCH 10/39] debug: will still fail but should trigger bc [testpypi] --- .github/workflows/package.yaml | 28 +++++++--------------------- 1 file changed, 7 insertions(+), 21 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index be4fd3f3..90dcccf1 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -3,6 +3,9 @@ on: push: branches: - master + # Release tags are v*, e.g., v0.8.0 or v1.0.0 + tags: + - v* pull_request: branches: - master @@ -21,7 +24,8 @@ jobs: run: pip install tox - name: Extract Commit Message # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env - run: echo "::set-env name=COMMIT_MESSAGE::$(git log -1 --pretty=%B)" + # https://help.github.com/en/actions/reference/contexts-and-expression-syntax-for-github-actions + run: echo "::set-env name=COMMIT_MESSAGE::$(git log -1 --pretty=%B ${{ github.event.after }})" # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the @@ -34,32 +38,14 @@ jobs: # number of seconds since the Unix epoch. While other options exist, this # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version - # TODO: we need to condition if NOT a tag - # if: contains(env.COMMIT_MESSAGE, '[testpypi]') + if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" - - name: DEBUG - env: - GITHUB_CONTEXT: ${{ toJson(github) }} - run: | - echo "$GITHUB_CONTEXT" - printenv - echo COMMIT_MESSAGE - echo "$COMMIT_MESSAGE" - echo SPHINX_BOOTSTRAP_THEME_DEV_VERSION - echo "$SPHINX_BOOTSTRAP_THEME_DEV_VERSION" - echo "git log -1" - git log -1 - echo "git rev-parse HEAD" - git rev-parse HEAD - echo "GITHUB_SHA=$GITHUB_SHA" - echo "github.sha = ${{ github.sha }}" - echo "github.ref = ${{ github.ref }}" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment # variable may or may not be set. If not, just use __version__ unchanged. - name: Package run: tox -e dist - name: Upload to Test PyPI - # if: contains(env.COMMIT_MESSAGE, '[testpypi]') + if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') uses: pypa/gh-action-pypi-publish@master with: user: __token__ From f67db95dbec3b291f3d951018e7be3700b492fce Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 08:09:42 -0500 Subject: [PATCH 11/39] the commit does not exist?! --- .github/workflows/package.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 90dcccf1..28011467 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -26,6 +26,8 @@ jobs: # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env # https://help.github.com/en/actions/reference/contexts-and-expression-syntax-for-github-actions run: echo "::set-env name=COMMIT_MESSAGE::$(git log -1 --pretty=%B ${{ github.event.after }})" + - name: DeBuG + run: git --no-pager log -10 # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the From 2bd90cc58c91a3308555376c79edde817455c9c8 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 09:02:49 -0500 Subject: [PATCH 12/39] debug: it can't actually be _this_ complicated?!! [testpypi] --- .github/workflows/package.yaml | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 28011467..41de7ebd 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -23,11 +23,15 @@ jobs: - name: Install Tox run: pip install tox - name: Extract Commit Message - # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env - # https://help.github.com/en/actions/reference/contexts-and-expression-syntax-for-github-actions - run: echo "::set-env name=COMMIT_MESSAGE::$(git log -1 --pretty=%B ${{ github.event.after }})" + run: | + # TODO: this can't really be the only way to get the commit message. + # NOTE: ${{ github.event.after }} -- can this be used instead? Will + # it also work for PRs from forks (not from branch)? + curl https://api.github.com/repos/${{ github.repository }}/commits/${{ github.ref }}/head > commit.json + msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" + echo "::set-env name=COMMIT_MESSAGE::$msg" - name: DeBuG - run: git --no-pager log -10 + run: echo ${{ github.event.head_commit.message }} # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the @@ -41,6 +45,7 @@ jobs: # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment # variable may or may not be set. If not, just use __version__ unchanged. From f7533f7674e9b2a516ce87df6e18cdf0805fca61 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 09:13:51 -0500 Subject: [PATCH 13/39] debug: [testpypi] check /head not /merge --- .github/workflows/package.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 41de7ebd..26d38a67 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -27,7 +27,10 @@ jobs: # TODO: this can't really be the only way to get the commit message. # NOTE: ${{ github.event.after }} -- can this be used instead? Will # it also work for PRs from forks (not from branch)? - curl https://api.github.com/repos/${{ github.repository }}/commits/${{ github.ref }}/head > commit.json + # For pull requests, github.ref will be e.g., refs/pull/XYZ/merge. We + # want to query the /head commit, so replace /merge with /head. + ref="$(echo '${{ github.ref }}' | sed 's@^\(refs/pull.*\)/merge$@\1/head@g')" + curl https://api.github.com/repos/${{ github.repository }}/commits/$ref/head > commit.json msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" echo "::set-env name=COMMIT_MESSAGE::$msg" - name: DeBuG From b4d9b20c0777bcc4d636fe29278015a806af9a32 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 09:16:29 -0500 Subject: [PATCH 14/39] debug omfg remove /head [testpypi] --- .github/workflows/package.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 26d38a67..0ceb7fe3 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -30,7 +30,7 @@ jobs: # For pull requests, github.ref will be e.g., refs/pull/XYZ/merge. We # want to query the /head commit, so replace /merge with /head. ref="$(echo '${{ github.ref }}' | sed 's@^\(refs/pull.*\)/merge$@\1/head@g')" - curl https://api.github.com/repos/${{ github.repository }}/commits/$ref/head > commit.json + curl https://api.github.com/repos/${{ github.repository }}/commits/$ref > commit.json msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" echo "::set-env name=COMMIT_MESSAGE::$msg" - name: DeBuG From c344b9068a21079dec6f319b80de37eb60c6e01e Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 09:21:37 -0500 Subject: [PATCH 15/39] confirmed ${{ github.event.head_commit.message }} DNE [testpypi] now we should fail with the expected message= --- .github/workflows/package.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 0ceb7fe3..57ebff0a 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -33,8 +33,6 @@ jobs: curl https://api.github.com/repos/${{ github.repository }}/commits/$ref > commit.json msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" echo "::set-env name=COMMIT_MESSAGE::$msg" - - name: DeBuG - run: echo ${{ github.event.head_commit.message }} # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the @@ -59,5 +57,7 @@ jobs: uses: pypa/gh-action-pypi-publish@master with: user: __token__ - password: pypi-${{ secrets.test_pypi_password }} + password: ${{ secrets.test_pypi_password }} repository_url: https://test.pypi.org/legacy/ + # TODO: add startsWith(github.event.ref, 'refs/tags/v') + # regular pypi upload (AKA: release tags) From 22fffcddb76be316b8fec97703b831ccba6dcf3e Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 09:42:28 -0500 Subject: [PATCH 16/39] ::set-env chokes on multiline commit message (but GITHUB_CONTEXT did not?!) i'm pretty over how limited this is ... [testpypi] --- .github/workflows/package.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 57ebff0a..5cad1546 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -31,8 +31,10 @@ jobs: # want to query the /head commit, so replace /merge with /head. ref="$(echo '${{ github.ref }}' | sed 's@^\(refs/pull.*\)/merge$@\1/head@g')" curl https://api.github.com/repos/${{ github.repository }}/commits/$ref > commit.json - msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" - echo "::set-env name=COMMIT_MESSAGE::$msg" + # msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" + # echo "::set-env name=COMMIT_MESSAGE::$msg" + true_or_false="$(python -c 'import json; print(str("[testpypi]" in json.load(open("commit.json"))["commit"]["message"]).lower())')" + echo "::set-env name=TEST_PYPI::$true_or_false" # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the @@ -45,7 +47,8 @@ jobs: # number of seconds since the Unix epoch. While other options exist, this # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version - if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + # if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + if: contains(env.TEST_PYPI, 'true') && !startsWith(github.event.ref, 'refs/tags/v') # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment @@ -53,7 +56,8 @@ jobs: - name: Package run: tox -e dist - name: Upload to Test PyPI - if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + # if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + if: contains(env.TEST_PYPI, 'true') && !startsWith(github.event.ref, 'refs/tags/v') uses: pypa/gh-action-pypi-publish@master with: user: __token__ From 5030d85eed5e2f77d7c8d692dfef0c21894cc4c6 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 10:08:47 -0500 Subject: [PATCH 17/39] debug: could it be that it exists? let us [testpypi] --- .github/workflows/package.yaml | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 5cad1546..a788a0a6 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -22,19 +22,6 @@ jobs: python-version: 3.x - name: Install Tox run: pip install tox - - name: Extract Commit Message - run: | - # TODO: this can't really be the only way to get the commit message. - # NOTE: ${{ github.event.after }} -- can this be used instead? Will - # it also work for PRs from forks (not from branch)? - # For pull requests, github.ref will be e.g., refs/pull/XYZ/merge. We - # want to query the /head commit, so replace /merge with /head. - ref="$(echo '${{ github.ref }}' | sed 's@^\(refs/pull.*\)/merge$@\1/head@g')" - curl https://api.github.com/repos/${{ github.repository }}/commits/$ref > commit.json - # msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" - # echo "::set-env name=COMMIT_MESSAGE::$msg" - true_or_false="$(python -c 'import json; print(str("[testpypi]" in json.load(open("commit.json"))["commit"]["message"]).lower())')" - echo "::set-env name=TEST_PYPI::$true_or_false" # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the @@ -47,8 +34,7 @@ jobs: # number of seconds since the Unix epoch. While other options exist, this # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version - # if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') - if: contains(env.TEST_PYPI, 'true') && !startsWith(github.event.ref, 'refs/tags/v') + if: !startsWith(github.event.ref, 'refs/tags/v') && contains(github.event.commits[0].message, '[testpypi]') # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment @@ -56,8 +42,7 @@ jobs: - name: Package run: tox -e dist - name: Upload to Test PyPI - # if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') - if: contains(env.TEST_PYPI, 'true') && !startsWith(github.event.ref, 'refs/tags/v') + if: !startsWith(github.event.ref, 'refs/tags/v') && contains(github.event.commits[0].message, '[testpypi]') uses: pypa/gh-action-pypi-publish@master with: user: __token__ From 9cba5053bc2fbd213797ef9298c200eaf99fa1e0 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 12 Feb 2020 10:15:52 -0500 Subject: [PATCH 18/39] debug: i guess I can't shortcircuit on tag, starting with ! is problem? let us again [testpypi] --- .github/workflows/package.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index a788a0a6..126363f9 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -34,7 +34,7 @@ jobs: # number of seconds since the Unix epoch. While other options exist, this # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version - if: !startsWith(github.event.ref, 'refs/tags/v') && contains(github.event.commits[0].message, '[testpypi]') + if: contains(github.event.commits[0].message, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment @@ -42,7 +42,7 @@ jobs: - name: Package run: tox -e dist - name: Upload to Test PyPI - if: !startsWith(github.event.ref, 'refs/tags/v') && contains(github.event.commits[0].message, '[testpypi]') + if: contains(github.event.commits[0].message, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') uses: pypa/gh-action-pypi-publish@master with: user: __token__ From 14c941cf6cea016ebc9ffac554739e5cd8301200 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Thu, 13 Feb 2020 02:05:17 -0500 Subject: [PATCH 19/39] i see, the api is different for push and pull_request so then now lets see can we [testpypi] --- .github/workflows/package.yaml | 36 ++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 126363f9..13febb9b 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -1,14 +1,14 @@ name: Package -on: - push: - branches: - - master - # Release tags are v*, e.g., v0.8.0 or v1.0.0 - tags: - - v* - pull_request: - branches: - - master +on: [push, pull_request] + # push: + # branches: + # - master + # # Release tags are v*, e.g., v0.8.0 or v1.0.0 + # tags: + # - v* + # pull_request: + # branches: + # - master # TODO: add tag here jobs: dist: @@ -22,6 +22,18 @@ jobs: python-version: 3.x - name: Install Tox run: pip install tox + - name: Extract Commit Message (Pull Request) + if: github.event_name == "pull_request" + run: | + echo "::set-env name=COMMIT_MESSAGE::$(git log --format=%B -n 1 ${{ github.event.after }})" + - name: Extract Commit Message (Push) + if: github.event_name == "push" + run: | + echo "::set-env name=COMMIT_MESSAGE::${{ github.event.head_commit.message }}" + - name: DEBUG COMMIT MESSAGE + run: | + echo "Commit Message" + echo "$COMMIT_MESSAGE" # If the commit message contains [testpypi] then we will want to configure # a "unique" dev version to package and later upload to Test PyPI, since # we cannot upload the same __version__ more than once. In the @@ -34,7 +46,7 @@ jobs: # number of seconds since the Unix epoch. While other options exist, this # is a simple way to create an increasing numerical "dev" version number. - name: Configure Test PyPI Version - if: contains(github.event.commits[0].message, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment @@ -42,7 +54,7 @@ jobs: - name: Package run: tox -e dist - name: Upload to Test PyPI - if: contains(github.event.commits[0].message, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') uses: pypa/gh-action-pypi-publish@master with: user: __token__ From 3b045dd070aea125f93bc91c595a53296085a648 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Thu, 13 Feb 2020 02:07:27 -0500 Subject: [PATCH 20/39] use 'pull_request' in single quotes, not "pull_request" because ... why?????!!!! [testpypi] please --- .github/workflows/package.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 13febb9b..fb48c455 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -23,11 +23,11 @@ jobs: - name: Install Tox run: pip install tox - name: Extract Commit Message (Pull Request) - if: github.event_name == "pull_request" + if: github.event_name == 'pull_request' run: | echo "::set-env name=COMMIT_MESSAGE::$(git log --format=%B -n 1 ${{ github.event.after }})" - name: Extract Commit Message (Push) - if: github.event_name == "push" + if: github.event_name == 'push' run: | echo "::set-env name=COMMIT_MESSAGE::${{ github.event.head_commit.message }}" - name: DEBUG COMMIT MESSAGE From c025214b14baddc6568fa2282b97f3d9288b7dff Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Thu, 13 Feb 2020 02:40:37 -0500 Subject: [PATCH 21/39] this is honestly pathetic close to rage quitting [testpypi] --- .github/workflows/package.yaml | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index fb48c455..5c472319 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -25,11 +25,27 @@ jobs: - name: Extract Commit Message (Pull Request) if: github.event_name == 'pull_request' run: | - echo "::set-env name=COMMIT_MESSAGE::$(git log --format=%B -n 1 ${{ github.event.after }})" + # For pull requests, github.ref will be e.g., refs/pull/XYZ/merge. We + # want to query the /head commit, so replace /merge with /head. + ref="$(echo '${{ github.ref }}' | sed 's@^\(refs/pull.*\)/merge$@\1/head@g')" + curl https://api.github.com/repos/${{ github.repository }}/commits/$ref > commit.json + msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" + # ::set-env and friends choke on multiline values, replace newlines. + # https://github.community/t5/GitHub-Actions/set-output-Truncates-Multiline-Strings/m-p/37870 + msg="${msg//'%'/'%25'}" + msg="${msg//$'\n'/'%0A'}" + msg="${msg//$'\r'/'%0D'}" + echo "::set-env name=COMMIT_MESSAGE::$msg" - name: Extract Commit Message (Push) if: github.event_name == 'push' run: | - echo "::set-env name=COMMIT_MESSAGE::${{ github.event.head_commit.message }}" + # ::set-env and friends choke on multiline values, replace newlines. + # https://github.community/t5/GitHub-Actions/set-output-Truncates-Multiline-Strings/m-p/37870 + msg="${{ github.event.head_commit.message }}" + msg="${msg//'%'/'%25'}" + msg="${msg//$'\n'/'%0A'}" + msg="${msg//$'\r'/'%0D'}" + echo "::set-env name=COMMIT_MESSAGE::$msg" - name: DEBUG COMMIT MESSAGE run: | echo "Commit Message" From cbb7bdd2901ad4d4f899defb0068eb27fa281318 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Thu, 13 Feb 2020 03:09:19 -0500 Subject: [PATCH 22/39] it works well enough, remove double builds --- .github/workflows/package.yaml | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 5c472319..86930e7a 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -1,15 +1,14 @@ name: Package -on: [push, pull_request] - # push: - # branches: - # - master - # # Release tags are v*, e.g., v0.8.0 or v1.0.0 - # tags: - # - v* - # pull_request: - # branches: - # - master -# TODO: add tag here +on: + push: + branches: + - master + # Release tags are v*, e.g., v0.8.0 or v1.0.0 + tags: + - v* + pull_request: + branches: + - master jobs: dist: name: Distribution From 7522bae44931bbe7ff1be98015948c745cf66b9d Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 26 Feb 2020 19:44:26 -0500 Subject: [PATCH 23/39] remove [testpypi] stuff --- .github/workflows/package.yaml | 59 ++-------------------------------- 1 file changed, 3 insertions(+), 56 deletions(-) diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml index 86930e7a..ccef6176 100644 --- a/.github/workflows/package.yaml +++ b/.github/workflows/package.yaml @@ -1,18 +1,14 @@ name: Package on: push: - branches: - - master # Release tags are v*, e.g., v0.8.0 or v1.0.0 tags: - v* - pull_request: - branches: - - master jobs: dist: name: Distribution runs-on: ubuntu-latest + if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags') steps: - uses: actions/checkout@v2 - name: Setup Python @@ -21,59 +17,10 @@ jobs: python-version: 3.x - name: Install Tox run: pip install tox - - name: Extract Commit Message (Pull Request) - if: github.event_name == 'pull_request' - run: | - # For pull requests, github.ref will be e.g., refs/pull/XYZ/merge. We - # want to query the /head commit, so replace /merge with /head. - ref="$(echo '${{ github.ref }}' | sed 's@^\(refs/pull.*\)/merge$@\1/head@g')" - curl https://api.github.com/repos/${{ github.repository }}/commits/$ref > commit.json - msg="$(python -c 'import json; print(json.load(open("commit.json"))["commit"]["message"])')" - # ::set-env and friends choke on multiline values, replace newlines. - # https://github.community/t5/GitHub-Actions/set-output-Truncates-Multiline-Strings/m-p/37870 - msg="${msg//'%'/'%25'}" - msg="${msg//$'\n'/'%0A'}" - msg="${msg//$'\r'/'%0D'}" - echo "::set-env name=COMMIT_MESSAGE::$msg" - - name: Extract Commit Message (Push) - if: github.event_name == 'push' - run: | - # ::set-env and friends choke on multiline values, replace newlines. - # https://github.community/t5/GitHub-Actions/set-output-Truncates-Multiline-Strings/m-p/37870 - msg="${{ github.event.head_commit.message }}" - msg="${msg//'%'/'%25'}" - msg="${msg//$'\n'/'%0A'}" - msg="${msg//$'\r'/'%0D'}" - echo "::set-env name=COMMIT_MESSAGE::$msg" - - name: DEBUG COMMIT MESSAGE - run: | - echo "Commit Message" - echo "$COMMIT_MESSAGE" - # If the commit message contains [testpypi] then we will want to configure - # a "unique" dev version to package and later upload to Test PyPI, since - # we cannot upload the same __version__ more than once. In the - # sphinx_bootstrap_theme/__init__.py we allow the environment variable - # SPHINX_BOOTSTRAP_THEME_DEV_VERSION to be appended to the current version - # - # __version__ += "dev" + $SPHINX_BOOTSTRAP_THEME_DEV_VERSION - # - # To make this version unique, we simply use `date +%s` which gives the - # number of seconds since the Unix epoch. While other options exist, this - # is a simple way to create an increasing numerical "dev" version number. - - name: Configure Test PyPI Version - if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') - # See: https://help.github.com/en/actions/reference/development-tools-for-github-actions#set-an-environment-variable-set-env - run: echo "::set-env name=SPHINX_BOOTSTRAP_THEME_DEV_VERSION::$(date +%s)" - # Run package test, SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment - # variable may or may not be set. If not, just use __version__ unchanged. - name: Package run: tox -e dist - - name: Upload to Test PyPI - if: contains(env.COMMIT_MESSAGE, '[testpypi]') && !startsWith(github.event.ref, 'refs/tags/v') + - name: Upload to PyPI uses: pypa/gh-action-pypi-publish@master with: user: __token__ - password: ${{ secrets.test_pypi_password }} - repository_url: https://test.pypi.org/legacy/ - # TODO: add startsWith(github.event.ref, 'refs/tags/v') - # regular pypi upload (AKA: release tags) + password: ${{ secrets.pypi_password }} From 86e9c38c009f8e6786467fc089c50e9ffff485e1 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 26 Feb 2020 21:00:09 -0500 Subject: [PATCH 24/39] add clean helper env, document how to use tox / tests --- demo/source/index.rst | 2 ++ demo/source/maintenance.rst | 72 +++++++++++++++++++++++++++++++++++++ tox.ini | 13 +++++++ 3 files changed, 87 insertions(+) create mode 100644 demo/source/maintenance.rst diff --git a/demo/source/index.rst b/demo/source/index.rst index f7a7b20a..4c3e8faf 100644 --- a/demo/source/index.rst +++ b/demo/source/index.rst @@ -30,10 +30,12 @@ Development history and feature wish lists. HISTORY TODO + maintenance .. Disabled. .. downloads + Indices and tables ================== diff --git a/demo/source/maintenance.rst b/demo/source/maintenance.rst new file mode 100644 index 00000000..d59c7c72 --- /dev/null +++ b/demo/source/maintenance.rst @@ -0,0 +1,72 @@ +Maintenance +=========== + +Testing Suite +------------- + +The ``sphinx-bootstrap-theme`` is developed using tox_. When contributing +changes, you can run the checks locally: + +.. _tox: https://tox.readthedocs.io/en/latest/ + +.. code-block:: bash + + # Install `tox` if you do not have it already, replace + # `pip` with your python package manager of choice. + $ pip install tox + + # Go to this repository's directory + $ cd /path/to/sphinx-bootstrap-theme + + # Run the default tests (py and lint). + $ tox + +A given check can be run explicitly provided that you supply the "environment +list" to ``tox``. For example, ``tox -e py`` runs the ``py`` environment. You +can run multiple using a comma separated list, e.g., ``tox -e py,lint``. The +available environments are as follows: + +.. cssclass:: table-striped table-bordered + ++---------------+--------------------------------------------------------------+ +| Test Name | Behavior | ++===============+==============================================================+ +| ``py`` | Run the python tests. This is the ``[testenv]`` section of | +| | ``tox.ini``. | +| | | +| | .. note:: No python tests are currently implemented! | ++---------------+--------------------------------------------------------------+ +| ``docs`` | Build the ``demo`` site documentation. The resultant | +| | documentation will be placed in | +| | ``{tox_workdir}/docs/tmp/html/``. Unless explicitly changed | +| | with ``--workdir`` argument to ``tox``, this will be the | +| | ``.tox`` directory created next to ``tox.ini``. | ++---------------+--------------------------------------------------------------+ +| ``linkcheck`` | Builds the ``demo`` site documentation and validates | +| | internal and external links all point to somewhere. | ++---------------+--------------------------------------------------------------+ +| ``server`` | Builds the ``demo`` site documentation using a local server. | +| | The server re-generates whenever changes are made, which can | +| | be convenient for iterative development. By default the | +| | port is ``8000``, if that port is in use supply the desired | +| | port to use. Example: ``tox -e server -- -p 8080``. Notice | +| | the ``--`` before ``-p 8080``. That is required, ``--`` | +| | tells ``tox`` that everything after the dashes should be | +| | ignored. In this case, the arguments after ``--`` are | +| | forwarded to sphinx-autobuild_. | ++---------------+--------------------------------------------------------------+ +| ``lint`` | Run any linting checks associated with the project. | ++---------------+--------------------------------------------------------------+ +| ``dist`` | Build the python source and wheel distributions in | +| | preparation for upload. Produces a top-level ``build/`` and | +| | ``dist/`` directory as a result. | +| | | +| | Manual uploads can be done using ``twine upload dist/*``. | ++---------------+--------------------------------------------------------------+ +| ``clean`` | Helper target to delete miscellaneous files that may be | +| | created as a result of development. For example, removes | +| | the ``build/`` and ``dist/`` directories that would be | +| | created by ``tox -e dist``. | ++---------------+--------------------------------------------------------------+ + +.. _sphinx-autobuild: https://github.com/GaretJax/sphinx-autobuild diff --git a/tox.ini b/tox.ini index 6bc25da0..0a603226 100644 --- a/tox.ini +++ b/tox.ini @@ -1,3 +1,5 @@ +# NOTE: adding / removing tests? Please update demo/source/maintenance.rst! + [tox] # By default, run tests and linting checks when invoking `tox`. envlist = py, lint @@ -74,3 +76,14 @@ commands = {envpython} setup.py bdist_wheel --universal twine check dist/* +# Dummy env for helping with cleanup of build related artifacts. +[testenv:clean] +skip_install = true +deps = +commands = + {envpython} -c "import os.path as osp; from shutil import rmtree; \ + root = '{toxinidir}'; \ + rmtree(osp.join(root, 'build')); \ + rmtree(osp.join(root, 'dist')); \ + rmtree(osp.join(root, 'sphinx_bootstrap_theme.egg-info')); \ + rmtree(osp.join(root, 'sphinx_bootstrap_theme', '__pycache__'))" From 816775574a045fe15f814b19caf0c81cbccbdff7 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 26 Feb 2020 21:00:55 -0500 Subject: [PATCH 25/39] propose new versioning scheme --- demo/source/maintenance.rst | 16 ++++++++++++++++ sphinx_bootstrap_theme/__init__.py | 13 +------------ 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/demo/source/maintenance.rst b/demo/source/maintenance.rst index d59c7c72..459353df 100644 --- a/demo/source/maintenance.rst +++ b/demo/source/maintenance.rst @@ -70,3 +70,19 @@ available environments are as follows: +---------------+--------------------------------------------------------------+ .. _sphinx-autobuild: https://github.com/GaretJax/sphinx-autobuild + +Versioning and Packaging +------------------------ + +The Sphinx Bootstrap Theme uses semantic versioning. The ``__version__`` +attribute defined in ``__init__.py`` is the current version of the theme. We +use the versioning tactics `described here`__, example scenario: + +1. Current version on ``master`` is ``0.8.0.dev``, it is time to release. +2. A commit sets the version to be ``0.8.0``, a pull request is opened to run + the test suite one last time. The PR is (rebase-)merged. +3. The merged commit is tagged as ``v0.8.0`` and the tag is pushed. This will + trigger the CI to deploy to PyPI. +4. After deployment, a new commit sets the version to be ``0.8.1.dev``. + +__ https://snarky.ca/how-i-manage-package-version-numbers/ diff --git a/sphinx_bootstrap_theme/__init__.py b/sphinx_bootstrap_theme/__init__.py index 239ca847..f3027f55 100644 --- a/sphinx_bootstrap_theme/__init__.py +++ b/sphinx_bootstrap_theme/__init__.py @@ -1,18 +1,7 @@ """Sphinx bootstrap theme.""" import os -VERSION = (0, 8, 0) - -__version__ = ".".join(str(v) for v in VERSION) -__version_full__ = __version__ - -# NOTE: SPHINX_BOOTSTRAP_THEME_DEV_VERSION environment variable is for internal -# usage only. It is used to create a dev release to deploy to TestPyPI, see -# .github/workflows/package.yaml for more information. -dev = os.getenv("SPHINX_BOOTSTRAP_THEME_DEV_VERSION", None) -if dev: - __version__ += ".dev" + dev - __version_full__ = __version__ +__version__ = "0.8.0.dev" def get_html_theme_path(): From adf2d46473ad70c6f8adc61da738f92eae3697c9 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 26 Feb 2020 22:11:39 -0500 Subject: [PATCH 26/39] [clean] need to ignore_errors for shutil.rmtree --- tox.ini | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tox.ini b/tox.ini index 0a603226..4f02c0f3 100644 --- a/tox.ini +++ b/tox.ini @@ -83,7 +83,7 @@ deps = commands = {envpython} -c "import os.path as osp; from shutil import rmtree; \ root = '{toxinidir}'; \ - rmtree(osp.join(root, 'build')); \ - rmtree(osp.join(root, 'dist')); \ - rmtree(osp.join(root, 'sphinx_bootstrap_theme.egg-info')); \ - rmtree(osp.join(root, 'sphinx_bootstrap_theme', '__pycache__'))" + rmtree(osp.join(root, 'build'), ignore_errors=True); \ + rmtree(osp.join(root, 'dist'), ignore_errors=True); \ + rmtree(osp.join(root, 'sphinx_bootstrap_theme.egg-info'), ignore_errors=True); \ + rmtree(osp.join(root, 'sphinx_bootstrap_theme', '__pycache__'), ignore_errors=True)" From b26674ba5fc26245de8e60060ee9c829e789fa1c Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Wed, 26 Feb 2020 22:12:25 -0500 Subject: [PATCH 27/39] deploy to GitHub Pages on tagged releases --- .github/workflows/github_pages.yaml | 50 +++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 .github/workflows/github_pages.yaml diff --git a/.github/workflows/github_pages.yaml b/.github/workflows/github_pages.yaml new file mode 100644 index 00000000..48cc3534 --- /dev/null +++ b/.github/workflows/github_pages.yaml @@ -0,0 +1,50 @@ +name: GitHub Pages +on: + push: + # Release tags are v*, e.g., v0.8.0 or v1.0.0 + tags: + - v* +jobs: + deploy: + name: Deploy + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: 3.x + - name: Install Tox + run: pip install tox + - name: Build and Deploy Website + run: | + set -exo + + # Gather current version number for comit message later. + version="$(python -c 'import sys; sys.path.insert(0, "."); from sphinx_bootstrap_theme import __version__; print(__version__)')" + + # Be explicit about --workdir so we know exactly where it is. + tox --workdir ./.tox -e docs + mv .tox/docs/tmp/html/ .. + tox -e clean # remove e.g., __pycache__ and friends + rm -rf .tox + git reset --hard # not necessary but not a problem either + + # Get the gh-pages branch with all the previous versions. + git remote -v + git fetch origin gh-pages + git checkout gh-pages + + # Delete everything and then re-add it. + git rm -r . + mv ../html/* . + touch .nojekyll + git add -Af . + git --no-pager status + git --no-pager diff --color=always + + # Configure and push. + git config --local user.name github-actions + git config --local user.email "notanemail@notanemail.org" + git commit -m "Version $version" + git push https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git From 87b8d7efd2ea92ba2aba2e6c959adc2977401fbd Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 02:11:11 -0700 Subject: [PATCH 28/39] small setup.py cleanup --- setup.py | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/setup.py b/setup.py index 6da9f3dc..bac24a43 100644 --- a/setup.py +++ b/setup.py @@ -1,9 +1,6 @@ -"""Sphinx Bootstrap Theme package.""" -import os -import setuptools +#!/usr/bin/env python -# Don't copy Mac OS X resource forks on tar/gzip. -os.environ['COPYFILE_DISABLE'] = "true" +import setuptools -# Setup the package. -setuptools.setup() +if __name__ == "__main__": + setuptools.setup() From c112180d5ee5471f4fb1afc99b78674618feb1e0 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 02:12:06 -0700 Subject: [PATCH 29/39] remove outdated tooling --- Makefile | 21 -------- fabfile.py | 140 ----------------------------------------------------- 2 files changed, 161 deletions(-) delete mode 100644 Makefile delete mode 100644 fabfile.py diff --git a/Makefile b/Makefile deleted file mode 100644 index 193d50b3..00000000 --- a/Makefile +++ /dev/null @@ -1,21 +0,0 @@ -# Makefile: For Python3 development. -# Because fabric doesn't work in Py3 :( - -.PHONY: clean demo demo_server - -clean: - rm -rf "dist" \ - "build" \ - "demo/build" \ - "sphinx_bootstrap_theme.egg-info" \ - -demo: - cd demo && make html - -# PORT allows you to specify a different port if say -# port 8000 is currently in use -# -# make demo_server PORT=8080 -PORT ?= 8000 -demo_server: demo - cd demo/build/html && python3 -m http.server $(PORT) diff --git a/fabfile.py b/fabfile.py deleted file mode 100644 index 574e3d95..00000000 --- a/fabfile.py +++ /dev/null @@ -1,140 +0,0 @@ -"""Fabric file.""" - -import base64 -import os -import json -import urllib2 - -from contextlib import contextmanager - -from fabric.api import local, lcd, abort -from fabric.decorators import task - -from sphinx_bootstrap_theme import __version__ - - -DL_DIR = "demo/source/_static/downloads" - -BUILD_DIRS = ( - "dist", - "build", - "demo/build", - "sphinx_bootstrap_theme.egg-info", -) - -SDIST_RST_FILES = ( - "README.rst", - "HISTORY.rst", -) -SDIST_TXT_FILES = [os.path.splitext(x)[0] + ".txt" for x in SDIST_RST_FILES] - - -############################################################################### -# Misc. -############################################################################### -@task -def clean(): - """Clean build files.""" - for build_dir in list(BUILD_DIRS): - local("rm -rf %s" % build_dir) - - -@task -def demo(): - """Build demo files.""" - with lcd("demo"): - local("make html") - - -@task -def demo_server(port="8000"): - """Serve demo from localhost. - - @param port Port to run server on. - """ - with lcd("demo/build/html"): - local("python -m SimpleHTTPServer %s" % port) - - -############################################################################### -# PyPI -############################################################################### -@contextmanager -def _dist_wrapper(): - """Add temporary distribution build files (and then clean up).""" - try: - # Copy select *.rst files to *.txt for build. - for rst_file, txt_file in zip(SDIST_RST_FILES, SDIST_TXT_FILES): - local("cp %s %s" % (rst_file, txt_file)) - - # Perform action. - yield - finally: - # Clean up temp *.txt files. - for rst_file in SDIST_TXT_FILES: - local("rm -f %s" % rst_file, capture=False) - - -@task -def sdist(): - """Package into distribution.""" - with _dist_wrapper(): - local("python setup.py sdist", capture=False) - - -@task -def pypi_register(): - """Register and prep user for PyPi upload. - - .. note:: May need to weak ~/.pypirc file per issue: - http://stackoverflow.com/questions/1569315 - """ - with _dist_wrapper(): - local("python setup.py register", capture=False) - - -@task -def pypi_upload(): - """Upload package.""" - with _dist_wrapper(): - local("python setup.py sdist upload", capture=False) - - -############################################################################### -# Downloads -############################################################################### -def get_rev(tag=True): - """Get build revision. - - @param tag Use git tag instead of hash? - """ - rev_cmd = "git describe --always --tag" if tag in (True, "True") else \ - "git rev-parse HEAD" - return local(rev_cmd, capture=True).strip() - - -@task -def zip_bundle(tag=True): - """Create zip file upload bundles. - - @param tag Use git tag instead of hash? - """ - #rev = get_rev(tag) - rev = __version__ - - print("Cleaning old build files.") - clean() - - local("mkdir -p build") - - print("Bundling new files.") - with lcd("sphinx_bootstrap_theme/bootstrap"): - local("zip -r ../../build/bootstrap.zip .") - - dest = os.path.abspath(os.path.join(DL_DIR, rev)) - with lcd("build"): - local("mkdir -p %s" % dest) - local("cp bootstrap.zip %s" % dest) - - print("Verifying contents.") - local("unzip -l bootstrap.zip") From 0eb67d24b955ceae3c4d04e8e016ec4e1e211ab4 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 02:30:07 -0700 Subject: [PATCH 30/39] add directions for how to develop --- README.rst | 58 +++++++++++++++++++++++++++--------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/README.rst b/README.rst index e5973e57..da5e5e30 100644 --- a/README.rst +++ b/README.rst @@ -286,35 +286,35 @@ Sphinx "_static" directory. Contributing ============ Contributions to this project are most welcome. Please make sure that the demo -site builds cleanly, and looks like what you want. We suggest using ``pipenv`` -to build this project:: - - $ cd sphinx-bootstrap-theme - $ pipenv install --dev - -Before working in this project directory, do:: - - $ pipenv shell - -Next, build the demo:: - - $ fab clean && fab demo - -Then, view the site in the development server:: - - $ fab demo_server - -Also, if you are adding a new type of styling or Sphinx or Bootstrap construct, -please add a usage example to the "Examples" page. - -**Note**: If you are in Python 3, Fabric isn't available, so we have a very -rough Makefile in its place. Try:: - - $ make clean && make demo - -Then, view the site in the development server:: - - $ make demo_server +site builds cleanly, and looks like what you want. This project uses `tox +`_ for development, once you have ``tox`` +installed (e.g., ``pip install tox``), change directories to the +``sphinx-bootstrap-theme`` top-level directory. + +- Building documentation: ``tox -e docs`` +- Validate html links in documentation: ``tox -e linkcheck`` +- Validate the code style: ``tox -e lint`` + +The encouraged way to develop with this package is to use a development server. +Changes made to files local in the repository will require rebuilding the +demo website, and using the development server will automate this process. + +1. In your terminal, execute ``tox -e server`` from the top level directory. + By default, this runs on port ``8000``. If this port is in use, a + pass-through argument to the underlying `sphinx-autobuild + `_ tool is required + such as ``tox -e server -- -p 8080``. The ``--`` between ``server`` and + ``-p`` are required, that signals the end of the arguments to ``tox`` and + everything after gets fed to ``sphinx-autobuild``. + +2. Open your browser of choice and visit `http://127.0.0.1:8000/ + `_ to see the server. + +3. Make any intended edits to the files in this repository. After the server + finishes rebuilding you can refresh your browser to see the updates. + +4. When finished, make sure to end the server from your terminal you ran + ``tox -e server`` with by issuing ``ctrl+c``. Licenses From be2d03a8abf825a3ef0ae6392f0011a0dc17d9c5 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 03:07:20 -0700 Subject: [PATCH 31/39] explain how to release things --- README.rst | 57 ++++++++++++++++++++++++++++++ sphinx_bootstrap_theme/__init__.py | 2 +- 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index da5e5e30..2ff799ee 100644 --- a/README.rst +++ b/README.rst @@ -316,6 +316,63 @@ demo website, and using the development server will automate this process. 4. When finished, make sure to end the server from your terminal you ran ``tox -e server`` with by issuing ``ctrl+c``. +Packaging +========= + +When a tag is pushed of the form ``vX.Y.Z`` (with the starting ``v``), it will +build the distribution using ``tox -e dist`` and uploaded to PyPI automatically. +Before pushing a tag, using Test PyPI should be done. In addition to ``tox``, +install `twine `_ +(``pip install twine``). + +.. code-block:: console + + # Build the distribution locally. + $ tox -e dist + + # Attempt uploading to Test PyPI + $ twine upload -r testpypi dist/* + +.. note:: + + The file ``sphinx_bootstrap_theme/__init__.py`` has the version number that + will be created. **Make sure it matches the tag you are creating**, once + an upload goes up it cannot be overwritten. If in preparing a release you + find an error and need to rebuild, simply increase the ``dev`` version + in ``__init__.py`` and then rebuild and reupload. For example: + + .. code-block:: diff + + --- a/sphinx_bootstrap_theme/__init__.py + +++ b/sphinx_bootstrap_theme/__init__.py + @@ -1,7 +1,7 @@ + """Sphinx bootstrap theme.""" + import os + + -__version__ = "0.8.0.dev0" + +__version__ = "0.8.0.dev1" + +After verifying that everything appears as desired on Test PyPI at the project +URL, one can also test the installation if desired: ``pip install +--index-url https://test.pypi.org/simple/ sphinx-bootstrap-theme`` + +Now that everything is validated, we are ready for release. + +1. Set the version number in ``sphinx_bootstrap_theme/__init__.py`` correctly. + E.g., for release ``0.8.0``, set ``__version__ = "0.8.0"`` without the + trailing ``dev`` qualifier. + +2. If desired, rebuild and upload to Test PyPI. Commit and push the changed + version number. Tag this commit ``git tag v0.8.0`` (note the leading ``v`` + is required for the CI/CD), and ``git push --tags``. This should initiate + the official release and upload it to PyPI (see the files + ``.github/workflows/{package,github_pages}.yaml`` for more). + +3. Now that the release is out, update the version number so that any users + installing from source do not believe they have an official release. E.g., + set ``__version__ = "0.8.1.dev0"``, commit and push this "dev version bump" + online. + Licenses ======== diff --git a/sphinx_bootstrap_theme/__init__.py b/sphinx_bootstrap_theme/__init__.py index f3027f55..60e15eea 100644 --- a/sphinx_bootstrap_theme/__init__.py +++ b/sphinx_bootstrap_theme/__init__.py @@ -1,7 +1,7 @@ """Sphinx bootstrap theme.""" import os -__version__ = "0.8.0.dev" +__version__ = "0.8.0.dev1" def get_html_theme_path(): From af8e2cf78ea7d0d87175009ce04e36d0e104b6c2 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 03:09:45 -0700 Subject: [PATCH 32/39] add explicit link to the Test PyPI site --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 2ff799ee..329a6f00 100644 --- a/README.rst +++ b/README.rst @@ -352,7 +352,8 @@ install `twine `_ -__version__ = "0.8.0.dev0" +__version__ = "0.8.0.dev1" -After verifying that everything appears as desired on Test PyPI at the project +After verifying that `everything appears as desired on Test PyPI +`_ at the project URL, one can also test the installation if desired: ``pip install --index-url https://test.pypi.org/simple/ sphinx-bootstrap-theme`` From f6256f7d845b79680b3e6529a1323bd41419f1fe Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 03:18:48 -0700 Subject: [PATCH 33/39] actually do some testing with py / sphinx versions --- tox.ini | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 4f02c0f3..e6a8f08f 100644 --- a/tox.ini +++ b/tox.ini @@ -12,8 +12,11 @@ deps = # On Unix, the double quotes are not necessary provided no spaces. sphinx{env:SPHINX_VERSION:} commands = - # TODO: create / add unit tests with pytest. + # Not really a test, but if we can build the docs then it works with this + # combination of python / sphinx. + {envpython} --version sphinx-build --version + sphinx-build -W -n -b html -d {envtmpdir}/doctrees source {envtmpdir}/html # Build demo site in nitpicky / warnings=error mode. [testenv:docs] From 05a666a2f5232bfb898a0f8df58b50a46f07d5ac Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 03:30:54 -0700 Subject: [PATCH 34/39] tests need changedir = demo --- tox.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/tox.ini b/tox.ini index e6a8f08f..a215b3d8 100644 --- a/tox.ini +++ b/tox.ini @@ -11,6 +11,7 @@ deps = # SPHINX_VERSION="==1.8.5" tox # On Unix, the double quotes are not necessary provided no spaces. sphinx{env:SPHINX_VERSION:} +changedir = demo commands = # Not really a test, but if we can build the docs then it works with this # combination of python / sphinx. From 13291f6ca201da23ea4ad0468201176b1b85fdc0 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 03:34:17 -0700 Subject: [PATCH 35/39] fix linting paths --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index a215b3d8..fa83c656 100644 --- a/tox.ini +++ b/tox.ini @@ -57,7 +57,7 @@ skip_install = true deps = flake8 commands = - flake8 {posargs} setup.py sphinx_bootstrap_theme + flake8 {posargs} {toxinidir}/setup.py {toxinidir}/sphinx_bootstrap_theme # Package for uploading to PyPI. Everything is put in dist/ folder. [testenv:dist] From 389ff91daa642dd8af99b5c8a54f955701f68439 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 04:00:53 -0700 Subject: [PATCH 36/39] fix homepage URL, if u testpyi upload its on the left --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 0a3a016e..9cb0a779 100644 --- a/setup.cfg +++ b/setup.cfg @@ -3,7 +3,7 @@ name = sphinx-bootstrap-theme version = attr: sphinx_bootstrap_theme.__version__ author = Ryan Roemer author-email = ryan@loose-bits.com -home-page = http://ryan-roemer.github.com/sphinx-bootstrap-theme/README.html +home-page = https://ryan-roemer.github.io/sphinx-bootstrap-theme/README.html description = Sphinx Bootstrap Theme. long_description = file: README.rst long_description_content_type = text/x-rst From 663e97e7b19b9d62c5249c2b1b5ace76148db96d Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 17:49:17 -0700 Subject: [PATCH 37/39] fix linkcheck errors, set to 0.8.0 for final test --- README.rst | 10 ++-- demo/source/conf.py | 5 ++ demo/source/examples.rst | 4 +- demo/source/index.rst | 1 - demo/source/maintenance.rst | 88 ------------------------------ sphinx_bootstrap_theme/__init__.py | 2 +- 6 files changed, 13 insertions(+), 97 deletions(-) delete mode 100644 demo/source/maintenance.rst diff --git a/README.rst b/README.rst index 329a6f00..d75bf41e 100644 --- a/README.rst +++ b/README.rst @@ -40,10 +40,10 @@ look at the `examples source`_ for the underlying reStructuredText). .. _United: http://bootswatch.com/united .. _Flatly: http://bootswatch.com/flatly .. _Sandstone: http://bootswatch.com/sandstone -.. _Sphinx Bootstrap Theme: http://ryan-roemer.github.com/sphinx-bootstrap-theme -.. _examples page: http://ryan-roemer.github.com/sphinx-bootstrap-theme/examples.html -.. _examples source: http://ryan-roemer.github.com/sphinx-bootstrap-theme/_sources/examples.rst.txt -.. _Django Cloud Browser: http://ryan-roemer.github.com/django-cloud-browser +.. _Sphinx Bootstrap Theme: https://ryan-roemer.github.io/sphinx-bootstrap-theme +.. _examples page: https://ryan-roemer.github.io/sphinx-bootstrap-theme/examples.html +.. _examples source: https://ryan-roemer.github.io/sphinx-bootstrap-theme/_sources/examples.rst.txt +.. _Django Cloud Browser: https://ryan-roemer.github.io/django-cloud-browser .. _seaborn: http://seaborn.pydata.org @@ -320,7 +320,7 @@ Packaging ========= When a tag is pushed of the form ``vX.Y.Z`` (with the starting ``v``), it will -build the distribution using ``tox -e dist`` and uploaded to PyPI automatically. +build the distribution using ``tox -e dist`` and upload to PyPI automatically. Before pushing a tag, using Test PyPI should be done. In addition to ``tox``, install `twine `_ (``pip install twine``). diff --git a/demo/source/conf.py b/demo/source/conf.py index 838e9351..fde58a5b 100644 --- a/demo/source/conf.py +++ b/demo/source/conf.py @@ -26,6 +26,11 @@ intersphinx_mapping = {'python': ('http://docs.python.org/', None)} +linkcheck_ignore = [ + '/_sources/examples.rst.txt', # from examples.rst + 'http://127.0.0.1:8000/' # from README.rst +] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/demo/source/examples.rst b/demo/source/examples.rst index 3b75cc8d..c08aba44 100644 --- a/demo/source/examples.rst +++ b/demo/source/examples.rst @@ -3,7 +3,7 @@ ========== Various examples of Bootstrap styling applied to Sphinx constructs. You can -view the `source <./_sources/examples.txt>`_ of this page to see the specific +view the `source `_ of this page to see the specific reStructuredText used to create these examples. Headings @@ -128,7 +128,7 @@ default Bootstrap ``table`` class. You can add additional table classes using the Sphinx ``cssclass::`` directive, as demonstrated in the following tables. -.. _rst_tables: https://www.sphinx-doc.org/en/latest/usage/restructuredtext/basics.html#tables +.. _rst_tables: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables Grid ---- diff --git a/demo/source/index.rst b/demo/source/index.rst index 4c3e8faf..b703f43f 100644 --- a/demo/source/index.rst +++ b/demo/source/index.rst @@ -30,7 +30,6 @@ Development history and feature wish lists. HISTORY TODO - maintenance .. Disabled. .. downloads diff --git a/demo/source/maintenance.rst b/demo/source/maintenance.rst deleted file mode 100644 index 459353df..00000000 --- a/demo/source/maintenance.rst +++ /dev/null @@ -1,88 +0,0 @@ -Maintenance -=========== - -Testing Suite -------------- - -The ``sphinx-bootstrap-theme`` is developed using tox_. When contributing -changes, you can run the checks locally: - -.. _tox: https://tox.readthedocs.io/en/latest/ - -.. code-block:: bash - - # Install `tox` if you do not have it already, replace - # `pip` with your python package manager of choice. - $ pip install tox - - # Go to this repository's directory - $ cd /path/to/sphinx-bootstrap-theme - - # Run the default tests (py and lint). - $ tox - -A given check can be run explicitly provided that you supply the "environment -list" to ``tox``. For example, ``tox -e py`` runs the ``py`` environment. You -can run multiple using a comma separated list, e.g., ``tox -e py,lint``. The -available environments are as follows: - -.. cssclass:: table-striped table-bordered - -+---------------+--------------------------------------------------------------+ -| Test Name | Behavior | -+===============+==============================================================+ -| ``py`` | Run the python tests. This is the ``[testenv]`` section of | -| | ``tox.ini``. | -| | | -| | .. note:: No python tests are currently implemented! | -+---------------+--------------------------------------------------------------+ -| ``docs`` | Build the ``demo`` site documentation. The resultant | -| | documentation will be placed in | -| | ``{tox_workdir}/docs/tmp/html/``. Unless explicitly changed | -| | with ``--workdir`` argument to ``tox``, this will be the | -| | ``.tox`` directory created next to ``tox.ini``. | -+---------------+--------------------------------------------------------------+ -| ``linkcheck`` | Builds the ``demo`` site documentation and validates | -| | internal and external links all point to somewhere. | -+---------------+--------------------------------------------------------------+ -| ``server`` | Builds the ``demo`` site documentation using a local server. | -| | The server re-generates whenever changes are made, which can | -| | be convenient for iterative development. By default the | -| | port is ``8000``, if that port is in use supply the desired | -| | port to use. Example: ``tox -e server -- -p 8080``. Notice | -| | the ``--`` before ``-p 8080``. That is required, ``--`` | -| | tells ``tox`` that everything after the dashes should be | -| | ignored. In this case, the arguments after ``--`` are | -| | forwarded to sphinx-autobuild_. | -+---------------+--------------------------------------------------------------+ -| ``lint`` | Run any linting checks associated with the project. | -+---------------+--------------------------------------------------------------+ -| ``dist`` | Build the python source and wheel distributions in | -| | preparation for upload. Produces a top-level ``build/`` and | -| | ``dist/`` directory as a result. | -| | | -| | Manual uploads can be done using ``twine upload dist/*``. | -+---------------+--------------------------------------------------------------+ -| ``clean`` | Helper target to delete miscellaneous files that may be | -| | created as a result of development. For example, removes | -| | the ``build/`` and ``dist/`` directories that would be | -| | created by ``tox -e dist``. | -+---------------+--------------------------------------------------------------+ - -.. _sphinx-autobuild: https://github.com/GaretJax/sphinx-autobuild - -Versioning and Packaging ------------------------- - -The Sphinx Bootstrap Theme uses semantic versioning. The ``__version__`` -attribute defined in ``__init__.py`` is the current version of the theme. We -use the versioning tactics `described here`__, example scenario: - -1. Current version on ``master`` is ``0.8.0.dev``, it is time to release. -2. A commit sets the version to be ``0.8.0``, a pull request is opened to run - the test suite one last time. The PR is (rebase-)merged. -3. The merged commit is tagged as ``v0.8.0`` and the tag is pushed. This will - trigger the CI to deploy to PyPI. -4. After deployment, a new commit sets the version to be ``0.8.1.dev``. - -__ https://snarky.ca/how-i-manage-package-version-numbers/ diff --git a/sphinx_bootstrap_theme/__init__.py b/sphinx_bootstrap_theme/__init__.py index 60e15eea..50e1238d 100644 --- a/sphinx_bootstrap_theme/__init__.py +++ b/sphinx_bootstrap_theme/__init__.py @@ -1,7 +1,7 @@ """Sphinx bootstrap theme.""" import os -__version__ = "0.8.0.dev1" +__version__ = "0.8.0" def get_html_theme_path(): From afad29a0bdd40eed4932aea41353cf7bea1135f0 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 17:53:50 -0700 Subject: [PATCH 38/39] fixup tox.ini pathing --- tox.ini | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index fa83c656..2bcc5295 100644 --- a/tox.ini +++ b/tox.ini @@ -37,6 +37,7 @@ commands = # Example run on port other than 8000: # tox -e server -- -p 8080 [testenv:server] +changedir = {toxinidir} usedevelop = true recreate = true deps = @@ -53,17 +54,18 @@ commands = # Linting checks. [testenv:lint] +changedir = {toxinidir} skip_install = true deps = flake8 commands = - flake8 {posargs} {toxinidir}/setup.py {toxinidir}/sphinx_bootstrap_theme + flake8 {posargs} setup.py sphinx_bootstrap_theme # Package for uploading to PyPI. Everything is put in dist/ folder. [testenv:dist] +changedir = {toxinidir} passenv = {[testenv]passenv} - SPHINX_BOOTSTRAP_THEME_DEV_VERSION skip_install = true deps = readme_renderer From 5ce7b5ca37e4f26cc3e896096083511b482996d5 Mon Sep 17 00:00:00 2001 From: Stephen McDowell Date: Fri, 10 Sep 2021 17:58:15 -0700 Subject: [PATCH 39/39] actually test tox -e dist to make sure packaging isnt broken in PRs --- .github/workflows/tests.yaml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 57f0cd06..2b486e0c 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -33,6 +33,19 @@ jobs: run: pip install tox - name: Build Docs run: tox -e docs + dist: + name: Dist + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v1 + with: + python-version: 3.x + - name: Install Tox + run: pip install tox + - name: Build Dist + run: tox -e dist linkcheck: name: Linkcheck runs-on: ubuntu-latest