From 8b76d27345c050ea7471107451dbd9d7a746cf3e Mon Sep 17 00:00:00 2001 From: Gwen Blum <19484478+gwenblum@users.noreply.github.com> Date: Mon, 18 Nov 2024 14:25:18 +0100 Subject: [PATCH] Update docs + readthedocs #49 * Doc requirements * sphinx-rtd-theme * Use add_stylesheet (add_stylesheet is deprecated) * Doc: Temporarily disable cython_highlighting extension (patch TypeError: 'CythonLexer' object is not callable) * Update requirements.txt * Update CHANGELOG * Update README.md --- .readthedocs.yaml | 6 ++-- CHANGELOG | 7 +++++ README.md | 17 +++++----- docs/conf.py | 6 ++-- docs/index.rst | 31 +++++++++---------- docs/install/docker.rst | 9 ++++++ docs/install/linuxmac.rst | 15 +++++++-- docs/install/steelhead.rst | 9 ++++++ docs/install/toc.rst | 16 ++++++++-- docs/install/windows.rst | 9 ++++++ ...{doc-requirements.txt => requirements.txt} | 11 ++++--- 11 files changed, 94 insertions(+), 42 deletions(-) rename docs/{doc-requirements.txt => requirements.txt} (77%) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index dd2aa46..31dbf0d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -30,6 +30,6 @@ sphinx: # 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 +python: + install: + - requirements: docs/requirements.txt diff --git a/CHANGELOG b/CHANGELOG index 488e3b0..02ee2ba 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,12 @@ CHANGELOG --------- +[24.10.1] +* Fix service issues with version (init with empty api_versions, ...) +* Add OAuth 2.0 +* Add custom payload for cookie auth +* Switch to pyreadline3 for Windows / Python 3.x +* Clean Dockerfile + [24.2.1] * Remove deprecated libs and functions (pkg_resources, datetime, gitpy_versioning) * Log warnings diff --git a/README.md b/README.md index 9116af0..97c36ab 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,12 @@ Riverbed SteelScript is a collection of libraries and scripts written in Python ## Quick Start -Here are 4 things you can do to start quick and easy with SteelScript. +Here are 4 things you can do to start quick and easy with SteelScript (click to expand the section).
Try examples just with git and Docker -### Quick Start SteelScript examples in a container +### Quick start SteelScript examples in a container If you have [git](https://git-scm.com/downloads) and [Docker](https://www.docker.com/get-started) installed, for example on a Linux machine in your lab. @@ -91,9 +91,9 @@ docker run --init --rm -p 8888:8888 --name=steelscript.notebook steelscript.note In the output, grab the url containing the *token*, for example *http://127.0.0.1:8888/tree?token=123456* , and open it in your browser to log into the Jupyter web-console. -From there, in the *Notebooks* folder you can find some notebook based on SteelScript: +From there, in the *Notebooks* folder you can find some notebooks based on SteelScript: -* **AppResponse**: 01-appresponse-hostgroups.ipynb +* **AppResponse**: [01-appresponse-hostgroups.ipynb](https://github.com/riverbed/steelscript-appresponse/blob/master/notebooks/01-appresponse-hostgroups.ipynb) * *work in progress* NetProfiler
@@ -101,7 +101,7 @@ From there, in the *Notebooks* folder you can find some notebook based on Steel
Try SteelScript notebooks in your own SteelScript environment, just with python, pip, git and vscode -### Quick Start SteelScript notebooks in your environment +### Quick start SteelScript notebooks in your environment If you have all the tools ready: 1. [Python](https://www.python.org/downloads) and pip @@ -143,9 +143,9 @@ pip install git+https://github.com/riverbed/steelscript-scc ## Get SteelScript -SteelScript and modules are distributed via [Riverbed in GitHub](https://github.com/riverbed). The main repository is [SteelScript](https://github.com/riverbed/steelscript). +SteelScript and modules are distributed via [Riverbed on GitHub](https://github.com/riverbed). The main repository is [SteelScript](https://github.com/riverbed/steelscript). -To use SteelScript, it is recommended to either build your own SteelScript container or install the SteelScript modules in your own Python environment directly from the source in GitHub main repository. Refer to the quickstarts in the section above - *the guide needs update*. +To use SteelScript, it is recommended to either build your own SteelScript container or install the SteelScript modules in your own Python environment directly from the source on GitHub main repository. Refer to the quickstarts in the section above - *the guide needs update*. > [!NOTE] > Other distributions have not been maintained and contain outdated versions of SteelScript: [*outdated* SteelScript on Dockerhub](https://hub.docker.com/r/riverbed/steelscript), [*outdated* SteelScript in pypi](https://pypi.org/search/?q=steelscript), ... @@ -214,6 +214,7 @@ The repos of SteelScript modules have a common structure │ └── __init__.py ├── tests ├── setup.py + ├── examples ├── notebooks └── tox.ini ``` @@ -224,7 +225,7 @@ Mandatory: - LICENSE: Riverbed Technology copyright, terms and conditions based on MIT - CHANGELOG: Simple text file tracking major changes - /docs: Documentation using reStructured Text (rst) file format. -- /examples: Python scripts samples showing how to use the module +- /examples: Python scripts samples showing how to use the module (only .py files) - /steelscript: The actual code, written in Python (Python 3). - /tests: Test plans and unit test. Can be organized in subfolders. Test plan are ideally documented and easy to run scripts but can be anything defining a test plan (script, text, ...), for example a Python script based on pytest. - setup.py: Python setup file containing meta descriptions and requirements. Based on setuptools, distutils and pytest. Should NOT contain unit test (use Tox and put unit test inside /tests folder instead) diff --git a/docs/conf.py b/docs/conf.py index 7a1e840..9b514d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,7 +42,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['sphinx.ext.autodoc', - 'cython_highlighting', +# 'cython_highlighting', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage'] @@ -65,7 +65,7 @@ # General information about the project. project = u'steelscript' -copyright = u'2020 Riverbed Technology, Inc.' +copyright = u'2019 - 2024 Riverbed Technology, Inc.' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -288,6 +288,6 @@ def setup(app): # add custom css that overrides the default theme - app.add_stylesheet('theme.css') + app.add_css_file('theme.css') # Register the docstring processor with sphinx #app.connect('autodoc-process-docstring', process_docstring) diff --git a/docs/index.rst b/docs/index.rst index fabd8c7..9a93154 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,21 +2,18 @@ Riverbed SteelScript for Python =============================== -.. warning:: - For quick starts and more about the latest version of `SteelScript `_ for Python 3, please refer to `SteelScript repository in GitHub `_ - This documentation has been created for SteelScript 2.0 at the time of Python 2 and has not been updated and reviewed for a while. - - -Welcome, this is the documentation of `Riverbed SteelScript `_ -The core `SteelScript `_ is a collection of Python modules that build upon REST APIs and other interfaces to interact with Riverbed appliances and software. +`SteelScript `_ is a collection of libraries and scripts in Python for interacting with `Riverbed `_ solutions and appliances, and other network infrastructure devices. +`SteelScript `_ is provided by `Riverbed `_ as an open source project on `GitHub `_ -Getting started with SteelScript (latest) -========================================= - -Please go to `SteelScript repository in GitHub `_ for quick starts and more about the latest version of `SteelScript `_ for **Python 3** +.. tip:: + Go to `SteelScript on GitHub `_ for quick starts and more about the latest `SteelScript `_ + +.. warning:: + + This documentation has been created for SteelScript 2.0 at the time of Python 2 and 3.8 and has not been updated and reviewed for a while. For latest information about SteelScript that works in containers, on Linux/Mac and Windows, supports Python 3.12+, notebooks and more, please refer to `SteelScript on GitHub `_ -*outdated* Getting started with SteelScript 2.0 for Python 2 +<<*outdated*>> SteelScript 2.0 for Python 2/3.8 <<*outdated*>> ========================================================== Installing @@ -25,8 +22,8 @@ Installing If you already have pip, just run the following (in a `virtualenv `_):: - $ pip install steelscript - $ steel install + pip install steelscript + steel install Not sure about pip, but you know you have Python? @@ -34,7 +31,7 @@ Not sure about pip, but you know you have Python? 2. Run it (in a `virtualenv `_):: - $ python steel_bootstrap.py install + python steel_bootstrap.py install Adding a module with steel command ---------------------------------- @@ -47,9 +44,9 @@ provided in this package. Once you have the base ``steelscript`` package installed, getting started is just one command away:: - $ steel install --steelhead + steel install --steelhead -For more details, see the :doc:`complete documentation `. +For more details, see the :doc:`doc of the steelscript module for SteelHead `. Documentation ------------- diff --git a/docs/install/docker.rst b/docs/install/docker.rst index ca1661c..40c35bb 100644 --- a/docs/install/docker.rst +++ b/docs/install/docker.rst @@ -1,6 +1,15 @@ SteelScript in a Docker ====================================== +.. tip:: + + Go to `SteelScript on GitHub `_ for quick starts and more about the latest `SteelScript `_ + +.. warning:: + + This documentation has been created for SteelScript 2.0 at the time of Python 2 and 3.8 and has not been updated and reviewed for a while. For latest information about SteelScript that works in containers, on Linux/Mac and Windows, supports Python 3.12+, notebooks and more, please refer to `SteelScript on GitHub `_ + + SteelScript for Python SDK - includes all of the core SteelScript packages in one simple container. Quickstart diff --git a/docs/install/linuxmac.rst b/docs/install/linuxmac.rst index 3810ff7..f865691 100644 --- a/docs/install/linuxmac.rst +++ b/docs/install/linuxmac.rst @@ -1,6 +1,15 @@ SteelScript Installation - Linux / Mac ====================================== +.. tip:: + + Go to `SteelScript on GitHub `_ for quick starts and more about the latest `SteelScript `_ + +.. warning:: + + This documentation has been created for SteelScript 2.0 at the time of Python 2 and 3.8 and has not been updated and reviewed for a while. For latest information about SteelScript that works in containers, on Linux/Mac and Windows, supports Python 3.12+, notebooks and more, please refer to `SteelScript on GitHub `_ + + This page provides step-by-step instructions for installing SteelScript and associated modules in the system-wide site-packages directory on a Linux or Mac. This will make SteelScript available to @@ -71,7 +80,7 @@ separate different projects from one another. $ . ~/steelscript/venv/bin/activate (venv)$ - .. note:: + .. tip:: Note how your prompt changes to include the name of the virtual environment. You can also confirm you are working within the new environment by checking which python executable is in your path:: @@ -171,7 +180,7 @@ and their dependencies instead of directly installing them. $ pip install --no-binary -d steelscript_packages steelscript.wireshark $ pip install --no-binary -d steelscript_packages virtualenv - .. note:: + .. tip:: The ``--no-binary`` option makes sure the packages can be installed on a barebones system that may not have ``pip`` available. @@ -214,7 +223,7 @@ and their dependencies instead of directly installing them. $ sudo steel install --pip-options="--no-index -f pkgs" - .. note:: + .. tip:: Omit ``sudo`` if you are using virtualenv, as admin privileges are not required diff --git a/docs/install/steelhead.rst b/docs/install/steelhead.rst index 169fa40..78d46ae 100644 --- a/docs/install/steelhead.rst +++ b/docs/install/steelhead.rst @@ -1,6 +1,15 @@ SteelScript SteelHead Installation ================================== +.. tip:: + + Go to `SteelScript on GitHub `_ for quick starts and more about the latest `SteelScript `_ + +.. warning:: + + This documentation has been created for SteelScript 2.0 at the time of Python 2 and 3.8 and has not been updated and reviewed for a while. For latest information about SteelScript that works in containers, on Linux/Mac and Windows, supports Python 3.12+, notebooks and more, please refer to `SteelScript on GitHub `_ + + The SteelScript SteelHead Package is distributed entirely as Python packages via the Python Package Index `PyPI `_. This makes it easy to install diff --git a/docs/install/toc.rst b/docs/install/toc.rst index 4001b91..382729c 100644 --- a/docs/install/toc.rst +++ b/docs/install/toc.rst @@ -1,14 +1,24 @@ SteelScript Installation ======================== -SteelScript is provided as open source on GitHub (https://github.com/riverbed). +.. tip:: + + Go to `SteelScript on GitHub `_ for quick starts and more about the latest `SteelScript `_ + +.. warning:: + + This documentation has been created for SteelScript 2.0 at the time of Python 2 and 3.8 and has not been updated and reviewed for a while. For latest information about SteelScript that works in containers, on Linux/Mac and Windows, supports Python 3.12+, notebooks and more, please refer to `SteelScript on GitHub `_ + + +`SteelScript ` is provided by `Riverbed `_ as an open source project on `GitHub `_ + Installation of SteelScript varies depending on the platform you are using. +The quickest and easiest installation method is probably the :doc:`Docker container `. + Start with the specific instructions for :doc:`Docker `, :doc:`Linux or Mac OS `, or :doc:`Windows ` for greater detail. -The quickest and easiest installation method is probably the :doc:`Docker container `. - Installing SteelScript SteelHead package requires executing the command ``steel install --steelhead``. But it might take a few more steps, see :doc:`SteelHead Installation Instructions ` for more details. diff --git a/docs/install/windows.rst b/docs/install/windows.rst index 186b9f6..bb28efa 100644 --- a/docs/install/windows.rst +++ b/docs/install/windows.rst @@ -1,6 +1,15 @@ SteelScript Installation - Windows ================================== +.. tip:: + + Go to `SteelScript on GitHub `_ for quick starts and more about the latest `SteelScript `_ + +.. warning:: + + This documentation has been created for SteelScript 2.0 at the time of Python 2 and 3.8 and has not been updated and reviewed for a while. For latest information about SteelScript that works in containers, on Linux/Mac and Windows, supports Python 3.12+, notebooks and more, please refer to `SteelScript on GitHub `_ + + This page provides step-by-step instructions for installing SteelScript and associated modules on Windows. diff --git a/docs/doc-requirements.txt b/docs/requirements.txt similarity index 77% rename from docs/doc-requirements.txt rename to docs/requirements.txt index 4fc269c..1c3b5d7 100644 --- a/docs/doc-requirements.txt +++ b/docs/requirements.txt @@ -1,12 +1,13 @@ -Cython==0.29.10 -recommonmark==0.5.0 -Sphinx==2.1.1 -sphinx-rtd-theme==0.4.3 +Cython +Sphinx +sphinx-rtd-theme +-e git+https://github.com/riverbed/steelscript.git#egg=steelscript -e git+https://github.com/riverbed/steelscript-appresponse.git#egg=steelscript.appresponse -e git+https://github.com/riverbed/steelscript-netprofiler.git#egg=steelscript.netprofiler --e git+https://github.com/riverbed/steelscript-wireshark.git#egg=steelscript.wireshark -e git+https://github.com/riverbed/steelscript-cmdline.git#egg=steelscript.cmdline -e git+https://github.com/riverbed/steelscript-scc.git#egg=steelscript.scc -e git+https://github.com/riverbed/steelscript-steelhead.git#egg=steelscript.steelhead +-e git+https://github.com/riverbed/steelscript-wireshark.git#egg=steelscript.wireshark +# -e git+https://github.com/riverbed/steelscript-packets.git#egg=steelscript.packets -e git+https://github.com/riverbed/reschema.git#egg=reschema -e git+https://github.com/riverbed/sleepwalker.git#egg=sleepwalker