Skip to content

Post-donation doc updates #1262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
absurdfarce merged 1 commit into from
Dec 5, 2025
Merged

Post-donation doc updates #1262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 3 additions & 6 deletions CONTRIBUTING.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ Contributions are welcome in the form of bug reports or pull requests.

Bug Reports
-----------
Quality bug reports are welcome at the `DataStax Python Driver JIRA <https://datastax-oss.atlassian.net/browse/PYTHON>`_.
Quality bug reports are welcome at the `CASSPYTHON project <https://issues.apache.org/jira/issues/?jql=project%20%3D%20CASSPYTHON%20ORDER%20BY%20key%20DESC>`_
of the ASF JIRA.

There are plenty of `good resources <http://www.drmaciver.com/2013/09/how-to-submit-a-decent-bug-report/>`_ describing how to create
good bug reports. They will not be repeated in detail here, but in general, the bug report include where appropriate:
Expand All @@ -18,11 +19,7 @@ good bug reports. They will not be repeated in detail here, but in general, the
Pull Requests
-------------
If you're able to fix a bug yourself, you can `fork the repository <https://help.github.com/articles/fork-a-repo/>`_ and submit a `Pull Request <https://help.github.com/articles/using-pull-requests/>`_ with the fix.
Please include tests demonstrating the issue and fix. For examples of how to run the tests, consult the `dev README <https://github.com/datastax/python-driver/blob/master/README-dev.rst#running-the-tests>`_.

Contribution License Agreement
------------------------------
To protect the community, all contributors are required to `sign the DataStax Contribution License Agreement <http://cla.datastax.com/>`_. The process is completely electronic and should only take a few minutes.
Please include tests demonstrating the issue and fix. For examples of how to run the tests, consult the `dev README <https://github.com/apache/cassandra-python-driver/blob/master/README-dev.rst#tests>`_.
Copy link
Contributor Author

@absurdfarce absurdfarce Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CLA no longer applies, and somehow we missed the fact that the relevant anchor in README-dev.rst had changed to "tests" a long time ago.


Design and Implementation Guidelines
------------------------------------
Expand Down
96 changes: 6 additions & 90 deletions README-dev.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
Releasing
=========
Note: the precise details of some of these steps have changed. Leaving this here as a guide only.

* Run the tests and ensure they all pass
* Update CHANGELOG.rst
* Check for any missing entries
Expand All @@ -13,7 +15,8 @@ Releasing
* Tag the release. For example: ``git tag -a 1.0.0 -m 'version 1.0.0'``
* Push the tag and new ``master``: ``git push origin 1.0.0 ; git push origin master``
* Update the `python-driver` submodule of `python-driver-wheels`,
commit then push. This will trigger TravisCI and the wheels building.
commit then push.
* Trigger the Github Actions necessary to build wheels for the various platforms
Copy link
Contributor Author

@absurdfarce absurdfarce Dec 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The wheel building process is now managed by Github Actions rather than Travis CI. This should be addressed in a more comprehensive way when python-driver-wheels is donated.

* For a GA release, upload the package to pypi::

# Clean the working directory
Expand Down Expand Up @@ -49,85 +52,12 @@ Releasing
* this is typically a matter of merging or rebasing onto master
* test and push updated branch to origin

* Update the JIRA versions: https://datastax-oss.atlassian.net/plugins/servlet/project-config/PYTHON/versions
* Update the JIRA releases: https://issues.apache.org/jira/projects/CASSPYTHON?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page

* add release dates and set version as "released"

* Make an announcement on the mailing list

Building the Docs
=================
Sphinx is required to build the docs. You probably want to install through apt,
if possible::

sudo apt-get install python-sphinx

pip may also work::

sudo pip install -U Sphinx

To build the docs, run::

python setup.py doc

Upload the Docs
=================

This is deprecated. The docs is now only published on https://docs.datastax.com.

To upload the docs, checkout the ``gh-pages`` branch and copy the entire
contents all of ``docs/_build/X.Y.Z/*`` into the root of the ``gh-pages`` branch
and then push that branch to github.

For example::

git checkout 1.0.0
python setup.py doc
git checkout gh-pages
cp -R docs/_build/1.0.0/* .
git add --update # add modified files
# Also make sure to add any new documentation files!
git commit -m 'Update docs (version 1.0.0)'
git push origin gh-pages

If docs build includes errors, those errors may not show up in the next build unless
you have changed the files with errors. It's good to occassionally clear the build
directory and build from scratch::

rm -rf docs/_build/*

Documentor
==========
We now also use another tool called Documentor with Sphinx source to build docs.
This gives us versioned docs with nice integrated search. This is a private tool
of DataStax.

Dependencies
------------
Sphinx
~~~~~~
Installed as described above

Documentor
~~~~~~~~~~
Clone and setup Documentor as specified in `the project <https://github.com/riptano/documentor#installation-and-quick-start>`_.
This tool assumes Ruby, bundler, and npm are present.

Building
--------
The setup script expects documentor to be in the system path. You can either add it permanently or run with something
like this::

PATH=$PATH:<documentor repo>/bin python setup.py doc

The docs will not display properly just browsing the filesystem in a browser. To view the docs as they would be in most
web servers, use the SimpleHTTPServer module::

cd docs/_build/
python -m SimpleHTTPServer

Then, browse to `localhost:8000 <http://localhost:8000>`_.

Copy link
Contributor Author

@absurdfarce absurdfarce Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentor isn't relevant anymore. We need to figure out how we want to render docs for this project; Sphinx is a possibility but Documentor isn't.

Tests
=====

Expand Down Expand Up @@ -166,7 +96,7 @@ it with the ``PROTOCOL_VERSION`` environment variable::

Testing Multiple Python Versions
--------------------------------
Use tox to test all of Python 3.9 through 3.13 and pypy (this is what TravisCI runs)::
Use tox to test all of Python 3.9 through 3.13 and pypy::
Copy link
Contributor Author

@absurdfarce absurdfarce Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Support for Travis CI has been removed


tox

Expand Down Expand Up @@ -223,17 +153,3 @@ An EAP release is only uploaded on a private server and it is not published on p
python setup.py doc

* Upload the docs on the EAP download server.

Adding a New Python Runtime Support
===================================

* Add the new python version to our jenkins image:
https://github.com/riptano/openstack-jenkins-drivers/

* Add the new python version in the Jenkinsfile and TravisCI configs as appropriate

* Run the tests and ensure they all pass
* also test all event loops

* Update the wheels building repo to support that version:
https://github.com/datastax/python-driver-wheels
Copy link
Contributor Author

@absurdfarce absurdfarce Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will be changed based on how CI is implemented for this project. The old model of managing Jenkins runners won't be in use here.

13 changes: 5 additions & 8 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,23 +63,20 @@ community) is now maintained as an integral part of this package. Refer to

Contributing
------------
See `CONTRIBUTING.md <https://github.com/datastax/python-driver/blob/master/CONTRIBUTING.rst>`_.

Error Handling
--------------
While originally written for the Java driver, users may reference the `Cassandra error handling done right blog <https://www.datastax.com/blog/cassandra-error-handling-done-right>`_ for resolving error handling scenarios with Apache Cassandra.
See `CONTRIBUTING.rst <https://github.com/datastax/python-driver/blob/master/CONTRIBUTING.rst>`_.
Copy link
Contributor Author

@absurdfarce absurdfarce Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link pointed to in the "Error Handling" section above no longer works. There's an ongoing discussion around removing this section entirely for the Java driver as well.


Reporting Problems
------------------
Please report any bugs and make any feature requests on the
`JIRA <https://datastax-oss.atlassian.net/browse/PYTHON>`_ issue tracker.
`CASSPYTHON project <https://issues.apache.org/jira/issues/?jql=project%20%3D%20CASSPYTHON%20ORDER%20BY%20key%20DESC>`_
of the ASF JIRA.

If you would like to contribute, please feel free to open a pull request.

Getting Help
------------
Your best options for getting help with the driver is the
`mailing list <https://groups.google.com/a/lists.datastax.com/forum/#!forum/python-driver-user>`_.
You can talk about the driver, ask questions and get help in the #cassandra-drivers channel on
`ASF Slack <https://the-asf.slack.com/>`_.
Copy link
Contributor Author

@absurdfarce absurdfarce Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@michaelsembwever We still reference the Google Group under "Mailing list" for the Java driver... I'd like to change that to something like this so that we can start pointing people to ASF Slack. Any objections?


License
-------
Expand Down