fix: Docs build (#71)

* Added description content type

* Change version on docs with bumpversion

* Updated docs build & theme

* Update repo URL.

Author: marksweb

.gitignore

@@ -16,5 +16,7 @@ __pycache__/
 build/
 dist/
 env/
+/*docs/env*/
+/*docs/_build*/
 
 local.sqlite

docs/Makefile

@@ -6,6 +6,8 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+VENV = env/bin/activate
+PORT = 8001
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -30,34 +32,49 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 
+install:
+	@echo "... setting up virtualenv"
+	python3 -m venv env
+	. $(VENV); pip install -r requirements.txt
+
+	@echo "\n" \
+	      "-------------------------------------------------------------------------------------------------- \n" \
+		    "* watch, build and serve the documentation: make run \n" \
+		    "* check spelling: make spelling \n" \
+		    "\n" \
+				"enchant must be installed in order for pyenchant (and therefore spelling checks) to work. See \n" \
+				"http://docs.django-cms.org/en/latest/contributing/documentation.html#install-the-spelling-software \n" \
+	      "-------------------------------------------------------------------------------------------------- \n" \
+
+
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	. $(VENV); $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	. $(VENV); $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	. $(VENV); $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	. $(VENV); $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	. $(VENV); $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	. $(VENV); $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@@ -66,24 +83,27 @@ qthelp:
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-classy-tags.qhc"
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	. $(VENV); $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	. $(VENV); $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	. $(VENV); $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
 doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	. $(VENV); $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+run:
+	. $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) build/html --host 0.0.0.0 --port $(PORT)

docs/conf.py

@@ -10,8 +10,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import os
-import sys
+import datetime
 
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -25,7 +24,9 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ["sphinx.ext.intersphinx"]
 
-intersphinx_mapping = {'django': ('http://readthedocs.org/projects/eric/django/docs/', None)}
+intersphinx_mapping = {
+    'django': ('https://docs.djangoproject.com/en/3.2/', 'https://docs.djangoproject.com/en/3.2/_objects/'),
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -39,18 +40,19 @@
 # The master toctree document.
 master_doc = 'index'
 
+current_year = datetime.datetime.now().year
 # General information about the project.
 project = 'django-classy-tags'
-copyright = '2010, Jonas Obrist'
+copyright = f'2010-{current_year}, Jonas Obrist'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+version = '3.0.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.0'
+release = '3.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -94,7 +96,15 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+try:
+    import furo
+
+    html_theme = 'furo'
+    html_theme_options = {
+        "navigation_with_keys": True,
+    }
+except ImportError:
+    html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/requirements.in

@@ -0,0 +1,9 @@
+MarkupSafe
+Pygments
+furo
+Sphinx>=4.2.0
+sphinxcontrib-spelling
+pyenchant>3
+sphinx-autobuild
+datetime
+pip-tools

docs/requirements.txt

@@ -0,0 +1,111 @@
+#
+# This file is autogenerated by pip-compile with python 3.9
+# To update, run:
+#
+#    pip-compile
+#
+--trusted-host pypi.python.org
+--trusted-host pypi.org
+--trusted-host files.pythonhosted.org
+
+alabaster==0.7.12
+    # via sphinx
+babel==2.9.1
+    # via sphinx
+beautifulsoup4==4.10.0
+    # via furo
+certifi==2021.10.8
+    # via requests
+charset-normalizer==2.0.10
+    # via requests
+click==8.0.3
+    # via pip-tools
+colorama==0.4.4
+    # via sphinx-autobuild
+datetime==4.3
+    # via -r requirements.in
+docutils==0.17.1
+    # via sphinx
+furo==2022.1.2
+    # via -r requirements.in
+idna==3.3
+    # via requests
+imagesize==1.3.0
+    # via sphinx
+importlib-metadata==4.10.1
+    # via sphinx
+jinja2==3.0.3
+    # via sphinx
+livereload==2.6.3
+    # via sphinx-autobuild
+markupsafe==2.0.1
+    # via
+    #   -r requirements.in
+    #   jinja2
+packaging==21.3
+    # via sphinx
+pep517==0.12.0
+    # via pip-tools
+pip-tools==6.4.0
+    # via -r requirements.in
+pyenchant==3.2.2
+    # via
+    #   -r requirements.in
+    #   sphinxcontrib-spelling
+pygments==2.11.2
+    # via
+    #   -r requirements.in
+    #   furo
+    #   sphinx
+pyparsing==3.0.7
+    # via packaging
+pytz==2021.3
+    # via
+    #   babel
+    #   datetime
+requests==2.27.1
+    # via sphinx
+six==1.16.0
+    # via livereload
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.3.1
+    # via beautifulsoup4
+sphinx==4.4.0
+    # via
+    #   -r requirements.in
+    #   furo
+    #   sphinx-autobuild
+    #   sphinxcontrib-spelling
+sphinx-autobuild==2021.3.14
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+sphinxcontrib-spelling==7.3.2
+    # via -r requirements.in
+tomli==2.0.0
+    # via pep517
+tornado==6.1
+    # via livereload
+urllib3==1.26.8
+    # via requests
+wheel==0.37.1
+    # via pip-tools
+zipp==3.7.0
+    # via importlib-metadata
+zope.interface==5.4.0
+    # via datetime
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip
+# setuptools

setup.cfg

@@ -11,20 +11,24 @@ replace = version='{new_version}'
 search = __version__ = '{current_version}'
 replace = __version__ = '{new_version}'
 
+[bumpversion:file:docs/conf.py]
+search = '{current_version}'
+replace = '{new_version}'
+
 [bumpversion:file:CHANGELOG.rst]
-search = 
+search =
 	unreleased
 	==========
-replace = 
+replace =
 	unreleased
 	==========
-	
+
 	{new_version} {utcnow:%%Y-%%m-%%d}
 	================
 
 [flake8]
 max-line-length = 119
-exclude = 
+exclude =
 	*.egg-info,
 	.eggs,
 	.env,

setup.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python
+from pathlib import Path
+
 from setuptools import find_packages, setup
 
 
@@ -29,6 +31,8 @@
     'Topic :: Software Development :: Libraries',
 ]
 
+this_directory = Path(__file__).parent
+long_description = (this_directory / "README.rst").read_text()
 
 setup(
     name='django-classy-tags',
@@ -37,10 +41,11 @@
     author_email='[email protected]',
     maintainer='Django CMS Association and contributors',
     maintainer_email='[email protected]',
-    url='http://github.com/ojii/django-classy-tags',
+    url='https://github.com/django-cms/django-classy-tags',
     license='BSD',
     description='Class based template tags for Django',
-    long_description=open('README.rst').read(),
+    long_description=long_description,
+    long_description_content_type='text/x-rst',
     packages=find_packages(exclude=['tests']),
     python_requires='>=3.7',
     include_package_data=True,