Merge pull request #506 from pystorm/fix-docs

Fix The Docs

Author: kbourgoin

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: Python package
+name: Tests
 
 on: [push]
 

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#   install:
+#     - requirements: docs/requirements.txt
+# test line - delete later

README.rst

@@ -1,6 +1,6 @@
 |logo|
 
-|Build Status|
+|Build Status| |Docs Status|
 
 Streamparse lets you run Python code against real-time streams of data via
 Apache Storm.  With streamparse you can create Storm bolts and spouts in
@@ -60,6 +60,10 @@ Roadmap
 See the `Roadmap <https://github.com/Parsely/streamparse/wiki/Roadmap>`__.
 
 .. |logo| image:: https://raw.githubusercontent.com/Parsely/streamparse/master/doc/source/images/streamparse-logo.png
-.. |Build Status| image:: https://travis-ci.org/Parsely/streamparse.svg?branch=master
-   :target: https://travis-ci.org/Parsely/streamparse
+.. |Build Status| image:: https://github.com/pystorm/streamparse/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/pystorm/streamparse/actions/workflows/test.yml
+   :alt: Build Status
+.. |Docs Status| image:: https://readthedocs.org/projects/streamparse/badge/?version=stable
+   :target: https://streamparse.readthedocs.io/en/stable/?badge=stable
+   :alt: Documentation Status
 .. |Demo| image:: https://raw.githubusercontent.com/Parsely/streamparse/master/doc/source/images/quickstart.gif

doc/source/api.rst renamed to doc/api.rst

@@ -17,7 +17,7 @@
 # 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("../../streamparse"))
+sys.path.insert(0, os.path.abspath("../streamparse"))
 from version import __version__ as VERSION
 
 # -- General configuration ------------------------------------------------
@@ -40,7 +40,7 @@
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+# source_suffix = {".rst": "restructuredtext"}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -50,7 +50,7 @@
 
 # General information about the project.
 project = "streamparse"
-copyright = "2014-2020, Parsely"
+copyright = "2014-2024, Parsely"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -277,4 +277,4 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

doc/source/conf.py renamed to doc/conf.py

@@ -9,8 +9,12 @@
 streamparse lets you run Python code against real-time streams of data.
 Integrates with Apache Storm.
 
-.. image:: https://travis-ci.org/Parsely/streamparse.svg?branch=master
-    :target: https://travis-ci.org/Parsely/streamparse
+.. image:: https://github.com/pystorm/streamparse/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/pystorm/streamparse/actions/workflows/test.yml
+   :alt: Build Status
+.. image:: https://readthedocs.org/projects/streamparse/badge/?version=stable
+   :target: https://streamparse.readthedocs.io/en/stable/?badge=stable
+   :alt: Documentation Status
 
 .. toctree::
    :maxdepth: 1

doc/source/develop.rst renamed to doc/develop.rst

@@ -135,7 +135,7 @@ topology in pure Python using Thrift.  For details see :ref:`topology_dsl`.
 Let's have a look at the definition file created by using the
 ``sparse quickstart`` command.
 
-.. literalinclude:: ../../streamparse/bootstrap/project/topologies/wordcount.py
+.. literalinclude:: ../streamparse/bootstrap/project/topologies/wordcount.py
     :language: python
 
 In the ``count_bolt`` bolt, we've told Storm that we'd like the stream of

doc/source/faq.rst renamed to doc/faq.rst

@@ -0,0 +1,33 @@
+Creating a new Streamparse Release
+==================================
+
+First, update the version number in ``version.py`` using `semantic versioning <https://semver.org>`_.
+
+Tag your commit with the new version number. For example::
+
+   git tag -a v0.1.0 -m "v0.1.0"
+
+Push the tag to GitHub::
+
+   git push origin v0.1.0
+
+Install twine and install build::
+
+   pip install twine
+   pip install build
+
+Build the package::
+
+   python -m build
+
+Upload the package to test.pypi.org::
+
+   twine upload --repository testpypi dist/*
+
+*Verify you can install it.* Then, upload it to pypi.org::
+
+   twine upload dist/*
+
+*Again, verify it installs correctly.* Then, finally, create a new release on GitHub.
+
+.. _SEMVER: https://semver.org

doc/source/images/quickstart.gif renamed to doc/images/quickstart.gif

@@ -36,11 +36,11 @@ Simple Python Example
 The first step to putting together a topology, is creating the bolts and spouts,
 so let's assume we have the following bolt and spout:
 
-.. literalinclude:: ../../examples/redis/src/bolts.py
+.. literalinclude:: ../examples/redis/src/bolts.py
     :language: python
     :lines: 1-28
 
-.. literalinclude:: ../../examples/redis/src/spouts.py
+.. literalinclude:: ../examples/redis/src/spouts.py
     :language: python
 
 One important thing to note is that we have added an ``outputs`` attribute to
@@ -51,7 +51,7 @@ objects.
 
 Now let's hook up the bolt to read from the spout:
 
-.. literalinclude:: ../../examples/redis/topologies/wordcount_mem.py
+.. literalinclude:: ../examples/redis/topologies/wordcount_mem.py
     :language: python
 
 .. note::
@@ -72,7 +72,7 @@ The topology DSL fully supports JVM-based bolts and spouts via the
 Here's an example of how we would use the
 `Storm Kafka Spout <http://storm.apache.org/releases/current/storm-kafka.html>`_:
 
-.. literalinclude:: ../../examples/kafka-jvm/topologies/pixelcount.py
+.. literalinclude:: ../examples/kafka-jvm/topologies/pixelcount.py
     :language: python
 
 One limitation of the Thrift interface we use to send the topology to Storm is
@@ -127,7 +127,7 @@ attribute. The most common grouping is probably the
 with the same value for the specified fields to the same executor. This can be
 seen in the prototypical word count topology:
 
-.. literalinclude:: ../../examples/redis/topologies/wordcount_mem.py
+.. literalinclude:: ../examples/redis/topologies/wordcount_mem.py
     :language: python