Python docstring type hints and code samples

[kieran-ryan]

🤔 What's changed?

• Extended and refactored Python docstrings (Google style)
  • Sample code snippets
  • Documented type hints
  • Corrections:
    • Dropped incomplete documentation for non-existant (parser_class) arg on public API
    • Code snippets such as assert "( a and ( b or not (c) ) )" == str(expression) raised errors (formatting in this case); or text11 = "not foo" = "(not foo)" being a syntax error
    • Typos e.g. Theses -> These
    • Corrected links such as relative #406 reference to cucumber/common#406 (tag-expressions: Add support for matching tags with wildcards common#406) following monorepo decoupling
• Dropped Python README.md

⚡️ What's your motivation?

• Improve user experience

  • Improved, accurate, tested documentation - assisting IDEs with type hinting where supported through docstrings
  • Code samples to install and run the library directly - useful for understanding and evaluating the API (compared to triggering a test runner for the same person) - currently missing

  

• Improve development

  • Snapshot testing through docs offers low barrier to evaluate implementation - nice in a polyglot repo; changing inputs and outputs and running pytest (or leveraging GitHub workflows), rather than modifying tests
  • Testing code snippet docs are runnable in workflows automates maintenance
  • Make type hints and purpose clear ahead of dropping Python versions in future
  • IDEs can provide configurations for running doctests through their UI

  

• Redundant, legacy Python README.md duplicates Python README.rst

🏷️ What kind of change is this?

• 📖 Documentation (improvements without changing code)

♻️ Anything particular you want feedback on?

• With existing Python 2 support, decided to add type hints within docstrings rather than within code (see type hints context in Python 3.5 release notes) and avoid breaking changes with this MR. Verbose in places with intention to replace with type hints and validation once relevant Python versions dropped.

📋 Checklist:

• I agree to respect and uphold the Cucumber Community Code of Conduct
• I have added/updated tests to cover my changes.
• My change requires a change to the documentation.
  • I have updated the documentation accordingly.
• Users should know about my change
  • I have added an entry to the "Unreleased" section of the CHANGELOG, linking to this pull request.