diff --git a/.cruft.json b/.cruft.json new file mode 100644 index 0000000..80339f0 --- /dev/null +++ b/.cruft.json @@ -0,0 +1,21 @@ +{ + "template": "https://github.com/sphinx-notes/cookiecutter", + "commit": "1701bf78ca498d756ce4502aa1712cfe23ed35af", + "checkout": null, + "context": { + "cookiecutter": { + "namespace": "sphinxnotes", + "name": "isso", + "full_name": "sphinxnotes-isso", + "author": "Shengyu Zhang", + "description": "Sphinx extension for embeding Isso comments in documents", + "version": "1.0", + "github_owner": "sphinx-notes", + "github_repo": "isso", + "pypi_name": "sphinxnotes-isso", + "pypi_owner": "SilverRainZ", + "_template": "https://github.com/sphinx-notes/cookiecutter" + } + }, + "directory": null +} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..5c14049 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,36 @@ +name: Publish New Release + +on: + push: + tags: + - "*" + +jobs: + pypi: + name: Publish package distributions to PyPI + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/sphinxnotes-isso + permissions: + id-token: write # IMPORTANT: this permission is mandatory for trusted publishing + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + - run: pip install build twine && make dist + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + password: ${{ secrets.PYPI_API_TOKEN }} + + release: + name: Publish Github Release + needs: [pypi] + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + - uses: ncipollo/release-action@v1 + with: + body: | + Changelog: https://sphinx.silverrainz.me/isso/changelog.html#version-${{ github.ref_name }} diff --git a/LICENSE b/LICENSE index e15ff86..c92f7fe 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Shengyu Zhang +Copyright (c) 2024, Shengyu Zhang All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/MANIFEST.in b/MANIFEST.in index ee400b7..4c868dc 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,5 @@ -# This file is generated from sphinx-notes/template. DO NOT EDIT. +# This file is generated from sphinx-notes/cookiecutter. +# You need to consider modifying the TEMPLATE or modifying THIS FILE. include LICENSE include README.rst diff --git a/Makefile b/Makefile index de889d9..5b37c2f 100644 --- a/Makefile +++ b/Makefile @@ -1,31 +1,58 @@ -# This file is generated from sphinx-notes/template. DO NOT EDIT. +# This file is generated from sphinx-notes/cookiecutter. +# You need to consider modifying the TEMPLATE or modifying THIS FILE. LANG = en_US.UTF-8 -MAKE = make -PY = python3 -RM = rm -rf - -.PHONY: docs test dist install upload test-upload sync-template +MAKE = make +PY = python3 +RM = rm -rf +# Build sphinx documentation. +.PHONY: docs docs: $(MAKE) -C docs/ +# Run unittest. +.PHONY: test test: $(PY) -m unittest discover -s tests -v +# Build distribution package, for "install" or "upload". +.PHONY: dist dist: pyproject.toml $(RM) dist/ # clean up old dist $(PY) -m build +# Install distribution package to user directory. +# +# NOTE: It may breaks your system-level packages, use at your own risk. +.PHONY: install install: dist + export PIP_BREAK_SYSTEM_PACKAGES=1 # required by Python 3.11+, see PEP-668 $(PY) -m pip install --user --no-deps --force-reinstall dist/*.whl +# Publish wheel to PyPI offical server when you want to +# You should have a PyPI account and have PyPI token configured. +# +# See also https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives +.PHONY: upload upload: dist $(PY) -m twine upload --repository pypi $. +.PHONY: upload-test +upload-test: dist $(PY) -m twine upload --repository testpypi $` +:Download: :tag:`{{ title }}` + +{% for line in content %} +{{ line }} +{% endfor %} + diff --git a/docs/changelog.rst b/docs/changelog.rst index b17ef48..a5dca91 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,24 +1,34 @@ +.. This file is generated from sphinx-notes/cookiecutter. + You need to consider modifying the TEMPLATE or modifying THIS FILE. + ========== Change Log ========== -2021-04-21 1.0 --------------- +.. Example: + + 1.0.0 + ===== + + .. version:: _ + :date: yyyy-mm-dd -.. sectionauthor:: Shengyu Zhang + Change log here. -- Use document title as Isso thread title +Version 1.x +=========== -2021-03-23 1.0a2 ----------------- +.. version:: 1.0 + :date: 2021-04-21 -.. sectionauthor:: Shengyu Zhang + - Use document title as Isso thread title -- Fixes: Thread ID should starts with slash +.. version:: 1.0a2 + :date: 2021-03-23 -2021-03-13 1.0a1 ----------------- + - Fixes: Thread ID should starts with slash -.. sectionauthor:: Shengyu Zhang +.. version:: 1.0a1 + :date: 2021-03-13 -The first version is out, enjoy~ + The first version is out, enjoy~ diff --git a/docs/conf.py b/docs/conf.py index 02e0efc..a46a665 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,6 @@ -# This file is generated from sphinx-notes/template. DO NOT EDIT. -# +# This file is generated from sphinx-notes/cookiecutter. +# You need to consider modifying the TEMPLATE or modifying THIS FILE. + # Configuration file for the Sphinx documentation builder. # # This file only contains a selection of the most common options. For a full @@ -13,28 +14,22 @@ project = 'sphinxnotes-isso' author = 'Shengyu Zhang' -copyright = "2023, " + author +copyright = "2024, " + author # The full version, including alpha/beta/rc tags -version = release = '1.0-5-ga40c37d' +version = release = '1.0' # -- General configuration --------------------------------------------------- -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('../src/sphinxnotes')) - # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.githubpages', - 'isso', + 'sphinx_design', + 'sphinx_copybutton', ] -isso_url = 'https://comments.silverrainz.me:30501' - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -75,4 +70,75 @@ # It is used to indicate the location of document like canonical_url html_baseurl = 'https://sphinx.silverrainz.me/isso' -html_logo = html_favicon = '_images/sphinx-notes.png' +html_logo = html_favicon = '_static/sphinx-notes.png' + +# -- Extensions ------------------------------------------------------------- + +# +extensions.append('sphinxnotes.any') +from sphinxnotes.any import Schema, Field as F +# +version_schema = Schema('version', + name=F(unique=True, referenceable=True, required=True, form=F.Form.LINES), + attrs={'date': F(referenceable=True)}, + content=F(form=F.Form.LINES), + description_template=open('_templates/version.rst', 'r').read(), + reference_template='🏷️{{ title }}', + missing_reference_template='🏷️{{ title }}', + ambiguous_reference_template='🏷️{{ title }}') +confval_schema = Schema('confval', + name=F(unique=True, referenceable=True, required=True, form=F.Form.LINES), + attrs={ + 'type': F(), + 'default': F(), + 'choice': F(form=F.Form.WORDS), + 'versionadded': F(), + 'versionchanged': F(form=F.Form.LINES), + }, + content=F(), + description_template=open('_templates/confval.rst', 'r').read(), + reference_template='⚙️{{ title }}', + missing_reference_template='⚙️{{ title }}', + ambiguous_reference_template='⚙️{{ title }}') +example_schema = Schema('example', + name=F(referenceable=True), + attrs={'style': F()}, + content=F(form=F.Form.LINES), + description_template=open('_templates/example.rst', 'r').read(), + reference_template='📝{{ title }}', + missing_reference_template='📝{{ title }}', + ambiguous_reference_template='📝{{ title }}') +# +any_schemas = [ + version_schema, + confval_schema, + example_schema, +] +primary_domain = 'any' +# + +extensions.append('sphinx.ext.extlinks') +extlinks = { + 'issue': ('https://github.com/sphinx-notes/isso/issues/%s', '💬%s'), + 'pull': ('https://github.com/sphinx-notes/isso/pull/%s', '🚀%s'), + 'tag': ('https://github.com/sphinx-notes/isso/releases/tag/%s', '🏷️%s'), +} + +extensions.append('sphinxcontrib.gtagjs') +gtagjs_ids = ['G-E4SNX0WZYV'] + +# +# -- Eat your own dog food -------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../src/sphinxnotes')) +extensions.append('isso') + +# DOG FOOD CONFIGURATION START + +isso_url = 'https://comments.silverrainz.me:30501' + +# DOG FOOD CONFIGURATION END +# diff --git a/docs/conf.rst b/docs/conf.rst index a362567..2bac8fe 100644 --- a/docs/conf.rst +++ b/docs/conf.rst @@ -1,24 +1,27 @@ +============= Configuration ============= -:isso_url: HTTP URL points to your Isso server +.. confval:: isso_url + + HTTP URL points to your Isso server. -The following configuration items are corresponding to `Isso Client Configuration`_ , +The following configuration items are corresponding to `Isso Client Configuration`_, please use Python's boolean, numeric value instead of string formatted value. -- isso_css -- isso_lang -- isso_reply_to_self -- isso_require_author -- isso_require_email -- isso_max_comments_top -- isso_max_comments_nested -- isso_reveal_on_click -- isso_avatar -- isso_avatar_bg -- isso_avatar_fg -- isso_vote -- isso_vote_levels -- isso_feed +- ``isso_css`` +- ``isso_lang`` +- ``isso_reply_to_self`` +- ``isso_require_author`` +- ``isso_require_email`` +- ``isso_max_comments_top`` +- ``isso_max_comments_nested`` +- ``isso_reveal_on_click`` +- ``isso_avatar`` +- ``isso_avatar_bg`` +- ``isso_avatar_fg`` +- ``isso_vote`` +- ``isso_vote_levels`` +- ``isso_feed`` .. _Isso Client Configuration: https://posativ.org/isso/docs/configuration/client/ diff --git a/docs/index.rst b/docs/index.rst index 8be2a82..a52d29e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,64 @@ -.. This file is generated from sphinx-notes/template. DO NOT EDIT. +.. This file is generated from sphinx-notes/cookiecutter. + You need to consider modifying the TEMPLATE or modifying THIS FILE. .. include:: ../README.rst Introduction ============ -.. include:: intro_for_index.rst +.. ADDITIONAL CONTENT START -You can quickly learn how to use this extension from :doc:`quickstart`. +The extension allows your embedding Isso_ comments in your Sphinx documentation: + +.. _Isso: https://isso-comments.de/ + +.. ADDITIONAL CONTENT END + +Getting Started +=============== + +.. note:: + + We assume you already have a Sphinx documentation, + if not, see `Getting Started with Sphinx`_. + +First, downloading extension from PyPI: + +.. code-block:: console + + $ pip install sphinxnotes-isso + +Then, add the extension name to ``extensions`` configuration item in your conf.py_: + +.. code-block:: python + + extensions = [ + # … + 'sphinxnotes.isso', + # … + ] + +.. _Getting Started with Sphinx: https://www.sphinx-doc.org/en/master/usage/quickstart.html +.. _conf.py: https://www.sphinx-doc.org/en/master/usage/configuration.html + +.. ADDITIONAL CONTENT START + +Set :confval:`isso_url` to the URL of your Isso server. + +.. code-block:: python + + isso_url = 'https://HOST:PORT' + +And then you can use directive ``isso`` to insert a Isso comment box, see +:doc:`usage` for more details. + +.. example:: + + .. isso:: + +Feel free to comment~ + +.. ADDITIONAL CONTENT END Contents ======== @@ -15,17 +66,14 @@ Contents .. toctree:: :caption: Contents - quickstart - install usage conf changelog - The Sphinx Notes Project ======================== -This project is a developed by `Shengyu Zhang`__, +The project is developed by `Shengyu Zhang`__, as part of **The Sphinx Notes Project**. .. toctree:: diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 414bd3c..0000000 --- a/docs/install.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. This file is generated from sphinx-notes/template. DO NOT EDIT. - -============ -Installation -============ - -.. highlight:: console - -.. note:: We assume you already have Python 3 environment and have pip_ in your ``PATH``. - -The easiest way of installation is downloading extension from PyPI (Python Package Index):: - - $ pip install sphinxnotes-isso - -.. _pip: https://pip.pypa.io/en/stable/ - -Install from Source -=================== - -If the version you need has not been published to PypI, you can install from source. - -pip can also install from git repository:: - - $ pip install git+https://github.com/sphinx-notes/isso.git@master - -Or you can clone repository to local:: - - $ git clone https://github.com/sphinx-notes/isso.git - -Then execute the following commands to build and install the extension:: - - $ make install diff --git a/docs/intro_for_index.rst b/docs/intro_for_index.rst deleted file mode 100644 index 1267c06..0000000 --- a/docs/intro_for_index.rst +++ /dev/null @@ -1,5 +0,0 @@ -The extension allows your embedding Isso__ comments like this: - -.. isso:: - -__ https://isso-comments.de/ diff --git a/docs/make.bat b/docs/make.bat index b3cafbd..b158787 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,4 +1,4 @@ -REM This file is generated from sphinx-notes/template. DO NOT EDIT. +REM This file is generated from sphinx-notes/cookiecutter. DO NOT EDIT. @ECHO OFF diff --git a/docs/quickstart.rst b/docs/quickstart.rst deleted file mode 100644 index e52ee20..0000000 --- a/docs/quickstart.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. This file is generated from sphinx-notes/template. DO NOT EDIT. - -=============== -Getting Started -=============== - -.. note:: - - We assume you already have a Sphinx documentation, - if not, see `Getting Started with Sphinx`_. - -First, downloading extension from PyPI (see :doc:`install` for more details): - -.. code-block:: console - - $ pip install sphinxnotes-isso - -Then, add the extension name to ``extensions`` configuration item in your conf.py_: - -.. code-block:: python - - extensions = [ - # … - 'sphinxnotes.isso', - # … - ] - -.. _Getting Started with Sphinx: https://www.sphinx-doc.org/en/master/usage/quickstart.html -.. _conf.py: https://www.sphinx-doc.org/en/master/usage/configuration.html - -.. include:: usage_for_quickstart.rst diff --git a/docs/usage.rst b/docs/usage.rst index 964a795..257075b 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -2,8 +2,6 @@ Usage ===== -.. note:: Before using the extension, you should have an Isso__ instance deployed. - The ``isso`` directive is used to insert a Isso comment box. The docname of current document is used as Isso thread ID. diff --git a/docs/usage_for_quickstart.rst b/docs/usage_for_quickstart.rst deleted file mode 100644 index c725ba1..0000000 --- a/docs/usage_for_quickstart.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. note:: Before using the extension, you should have an Isso__ instance deployed. - -Still in conf.py, set ``isso_url`` :doc:`conf` item to the URL of your Isso instance. - -.. code-block:: py - - isso_url = 'https://HOST:PORT' - -Then use directive ``isso`` to embed Isso comment box to your doccument: - -.. code-block:: rst - - .. isso:: - -Just like this: - -.. isso:: - -Feel free to comment~ - -__ https://isso-comments.de/ diff --git a/pyproject.toml b/pyproject.toml index d077c36..823e43e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,6 @@ -# This file is generated from sphinx-notes/template. DO NOT EDIT. -# +# This file is generated from sphinx-notes/cookiecutter. +# You need to consider modifying the TEMPLATE or modifying THIS FILE. + # This file is used to configure your project. # Read more about the various options under: # https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#declaring-project-metadata @@ -33,9 +34,21 @@ dependencies = [ dynamic = ["version"] # required by setuptools_scm, see section [build-system] [project.optional-dependencies] -docs = ["furo"] -test = ["pytest"] -dev = ["build", "twine"] +dev = [ + "build", + "twine", + "cruft", +] +test = [ + "pytest", +] +docs = [ + "furo", + "sphinxnotes-any", + "sphinx_design", + "sphinx_copybutton", + "sphinxcontrib-gtagjs", +] [project.urls] homepage = "https://sphinx.silverrainz.me/isso"