Publish the change log on RTD.

Fixes #188

Some other minor modernizations as well:
- use a RTD config file
- Rename NEWS to CHANGES.rst as seems to be th current standard
- Likewise, rename doc to docs and *.txt to *.rst (hooray syntax highlighting)
- Partially require setuptools; we effectively did anyway. More work required here.

.gitignore

@@ -7,7 +7,7 @@ dist/
 .tox/
 wheelhouse/
 greenlet.egg-info/
-/doc/_build
+/docs/_build
 __pycache__/
 /.ropeproject/
 /MANIFEST

.readthedocs.yml

@@ -0,0 +1,19 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

NEWS → CHANGES.rst

@@ -1,15 +1,27 @@
-0.4.17
-======
+=========
+ Changes
+=========
+
+1.0.0 (unreleased)
+==================
+
+- (Packaging) Require setuptools to build from source.
+- (Packaging) Stop asking setuptools to build both .tar.gz and .zip
+  sdists. PyPI has standardized on .tar.gz for all platforms.
+- (Documentation) Publish the change log to https://greenlet.readthedocs.io
+
+0.4.17 (2020-09-22)
+===================
 - Support for PEP 567 ContextVars
 
 0.4.16
-===========
+======
 - Support for DEC Alpha architecture
 - Support for Python 3.9
 - Support for Python 3.10a0
 
 0.4.15
-===========
+======
 - Support for RISC-V architecture
 - Workaround a gcc bug on ppc64
 
@@ -49,16 +61,16 @@
 
 0.4.7
 =====
-- Added a missing workaround for `return 0` on mips
+- Added a missing workaround for ``return 0`` on mips
 - Restore compatibility with Python 2.5
 - Fixed stack switching on sparc
 
 0.4.6
 =====
-- Expose `_stack_saved` property on greenlet objects, it may be used to
+- Expose ``_stack_saved`` property on greenlet objects, it may be used to
   introspect the amount of memory used by a saved stack, but the API is
   subject to change in the future
-- Added a workaround for `return 0` compiler optimizations on all
+- Added a workaround for ``return 0`` compiler optimizations on all
   architectures
 - C API typo fixes
 

MANIFEST.in

@@ -1,24 +1,27 @@
 include .travis.yml
+include .readthedocs.yml
 include AUTHORS
 include LICENSE
 include LICENSE.PSF
 include MANIFEST.in
-include NEWS
+include CHANGES.rst
 include README.rst
 include appveyor.yml
 include appveyor/run_pip.py
 include appveyor/run_with_env.cmd
 include benchmarks/chain.py
 include conftest.py
 include dev-requirements.txt
-include doc/Makefile
-include doc/conf.py
-include doc/greenlet.txt
-include doc/index.txt
-include doc/make.bat
+include docs/Makefile
+include docs/conf.py
+include docs/greenlet.rst
+include docs/index.rst
+include docs/changes.rst
+include docs/make.bat
 include greenlet.c
 include greenlet.h
 include make-manylinux
+include make-manifest
 include make-win-release
 include my_build_ext.py
 include platform/switch_aarch64_gcc.h

README.rst

@@ -40,15 +40,13 @@ alternative to Python's built in coroutine support:
 Getting Greenlet
 ================
 
-The easiest way to get Greenlet is to install it with pip or
-easy_install::
+The easiest way to get Greenlet is to install it with pip::
 
   pip install greenlet
-  easy_install greenlet
 
 
 Source code archives and windows installers are available on the
-python package index at https://pypi.python.org/pypi/greenlet
+python package index at https://pypi.org/project/greenlet
 
 The source code repository is hosted on github:
 https://github.com/python-greenlet/greenlet

docs/changes.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst

doc/conf.py → docs/conf.py

@@ -17,21 +17,30 @@
 # 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('.'))
-
+import pkg_resources
+sys.path.append(os.path.abspath('../')) # XXX: Move to src directory
+rqmt = pkg_resources.require('greenlet')[0]
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+ ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []  # ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.txt'
+source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -48,9 +57,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.4'
+version = '%s.%s' % tuple(map(int, rqmt.version.split('.')[:2]))
 # The full version, including alpha/beta/rc tags.
-release = '0.4.0'
+release = rqmt.version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -240,3 +249,18 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+intersphinx_mapping = {
+    'https://docs.python.org/': None,
+}
+
+
+# Sphinx 1.8+ prefers this to `autodoc_default_flags`. It's documented that
+# either True or None mean the same thing as just setting the flag, but
+# only None works in 1.8 (True works in 2.0)
+autodoc_default_options = {
+    'members': None,
+    'show-inheritance': None,
+}
+autodoc_member_order = 'bysource'
+autoclass_content = 'both'

doc/greenlet.txt → docs/greenlet.rst

@@ -1,8 +1,13 @@
-=====================================================
-greenlet: Lightweight concurrent programming
-=====================================================
-.. toctree::
-   :maxdepth: 2
+==============================================
+ greenlet: Lightweight concurrent programming
+==============================================
+
+.. TODO: Refactor and share the opening paragraphs with README.rst
+.. TODO: Break into a few pieces: Introduction, tutorial, API
+   reference, etc.
+
+
+.. sphinx-include-begin
 
 Motivation
 ==========
@@ -13,15 +18,15 @@ pseudo-concurrently (typically in a single or a few OS-level threads) and
 are synchronized with data exchanges on "channels".
 
 A "greenlet", on the other hand, is a still more primitive notion of
-micro-thread with no implicit scheduling; coroutines, in other words.  
+micro-thread with no implicit scheduling; coroutines, in other words.
 This is useful when you want to
 control exactly when your code runs.  You can build custom scheduled
 micro-threads on top of greenlet; however, it seems that greenlets are
-useful on their own as a way to make advanced control flow structures.  
+useful on their own as a way to make advanced control flow structures.
 For example, we can recreate generators; the difference with Python's own
 generators is that our generators can call nested functions and the nested
 functions can yield values too.  (Additionally, you don't need a "yield"
-keyword.  See the example in ``test/test_generator.py``). 
+keyword.  See the example in ``test/test_generator.py``).
 
 Greenlets are provided as a C extension module for the regular unmodified
 interpreter.
@@ -54,7 +59,7 @@ read_next_char() function needed by the code above.  We have two incompatible
 functions::
 
     def event_keydown(key):
-        ?? 
+        ??
 
     def read_next_char():
         ?? should wait for the next event_keydown() call
@@ -138,7 +143,7 @@ For example::
     gr1.switch()
 
 The last line jumps to test1, which prints 12, jumps to test2, prints 56,
-jumps back into test1, prints 34; and then test1 finishes and gr1 dies.  
+jumps back into test1, prints 34; and then test1 finishes and gr1 dies.
 At this point, the execution comes back to the original ``gr1.switch()``
 call.  Note that 78 is never printed.
 
@@ -153,12 +158,12 @@ organized in a tree.  Top-level code that doesn't run in a user-created
 greenlet runs in the implicit "main" greenlet, which is the root of the
 tree.
 
-In the above example, both gr1 and gr2 have the main greenlet as a parent.  
+In the above example, both gr1 and gr2 have the main greenlet as a parent.
 Whenever one of them dies, the execution comes back to "main".
 
 Uncaught exceptions are propagated into the parent, too.  For example, if
 the above test2() contained a typo, it would generate a NameError that
-would kill gr2, and the exception would go back directly into "main".  
+would kill gr2, and the exception would go back directly into "main".
 The traceback would show test2, but not test1.  Remember, switches are not
 calls, but transfer of execution between parallel "stack containers", and
 the "parent" defines which stack logically comes "below" the current one.
@@ -222,7 +227,7 @@ Here are the precise rules for sending objects around:
     will start to run now.
 
 Dying greenlet
-    If a greenlet's ``run()`` finishes, its return value is the object 
+    If a greenlet's ``run()`` finishes, its return value is the object
     sent to its parent.  If ``run()`` terminates with an exception, the
     exception is propagated to its parent (unless it is a
     ``greenlet.GreenletExit`` exception, in which case the exception

docs/index.rst

@@ -0,0 +1,11 @@
+==============================================
+ greenlet: Lightweight concurrent programming
+==============================================
+
+.. toctree::
+   :maxdepth: 1
+
+   changes
+
+.. include:: greenlet.rst
+   :start-after: sphinx-include-begin

setup.cfg

@@ -1,2 +0,0 @@
-[sdist]
-formats=gztar zip

setup.py

@@ -1,38 +1,37 @@
 #! /usr/bin/env python
 
-import sys, os, glob, platform, tempfile, shutil
+import sys
+import os
+import glob
+import platform
+
+# distutils is deprecated and vendored into setuptools now.
+from setuptools import setup
+from setuptools import Extension
+
+# XXX: This uses distutils directly and is probably
+# unnecessary with setuptools.
+from my_build_ext import build_ext
 
 # workaround segfaults on openbsd and RHEL 3 / CentOS 3 . see
 # https://bitbucket.org/ambroff/greenlet/issue/11/segfault-on-openbsd-i386
 # https://github.com/python-greenlet/greenlet/issues/4
 # https://github.com/python-greenlet/greenlet/issues/94
+# pylint:disable=too-many-boolean-expressions
 if ((sys.platform == "openbsd4" and os.uname()[-1] == "i386")
     or ("-with-redhat-3." in platform.platform() and platform.machine() == 'i686')
     or (sys.platform == "sunos5" and os.uname()[-1] == "sun4v")
     or ("SunOS" in platform.platform() and platform.machine() == "sun4v")
     or (sys.platform == "linux" and platform.machine() == "ppc")):
     os.environ["CFLAGS"] = ("%s %s" % (os.environ.get("CFLAGS", ""), "-Os")).lstrip()
 
-try:
-    if not (sys.modules.get("setuptools")
-            or "develop" in sys.argv
-            or "upload" in sys.argv
-            or "bdist_egg" in sys.argv
-            or "bdist_wheel" in sys.argv
-            or "test" in sys.argv):
-        raise ImportError()
-    from setuptools import setup, Extension
-    setuptools_args = dict(test_suite='tests.test_collector', zip_safe=False)
-except ImportError:
-    from distutils.core import setup, Extension
-    setuptools_args = dict()
 
 def readfile(filename):
-    f = open(filename)
-    try:
+    # The with statement is from Python 2.6, meaning we definitely no longer
+    # support 2.4 or 2.5. I strongly suspect that's not a problem; we'll be dropping
+    # our claim to support them very soon anyway.
+    with open(filename, 'r') as f:
         return f.read()
-    finally:
-        f.close()
 
 def _find_platform_headers():
     return glob.glob("platform/switch_*.h")
@@ -64,16 +63,17 @@ def _find_platform_headers():
         extra_compile_args=extra_compile_args,
         depends=['greenlet.h', 'slp_platformselect.h'] + _find_platform_headers())]
 
-from distutils.core import Command
-from my_build_ext import build_ext
-
-
 setup(
     name="greenlet",
     version='0.4.17',
     description='Lightweight in-process concurrent programming',
     long_description=readfile("README.rst"),
     url="https://github.com/python-greenlet/greenlet",
+    project_urls={
+        'Bug Tracker': 'https://github.com/python-greenlet/greenlet/issues',
+        'Source Code': 'https://github.com/python-greenlet/gevent/',
+        'Documentation': 'https://greenlet.readthedocs.io/',
+    },
     license="MIT License",
     platforms=['any'],
     headers=headers,
@@ -102,5 +102,12 @@ def _find_platform_headers():
         'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',
         'Operating System :: OS Independent',
-        'Topic :: Software Development :: Libraries :: Python Modules'],
-    **setuptools_args)
+        'Topic :: Software Development :: Libraries :: Python Modules'
+    ],
+    extras_require={
+        'docs': [
+            'Sphinx',
+        ]
+    }
+
+)