-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
11 changed files
with
404 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
# Copyright Jiaqi Liu | ||
# | ||
# Licensed under the Apache License, Version 2.0 (the "License"); | ||
# you may not use this file except in compliance with the License. | ||
# You may obtain a copy of the License at | ||
# | ||
# http://www.apache.org/licenses/LICENSE-2.0 | ||
# | ||
# Unless required by applicable law or agreed to in writing, software | ||
# distributed under the License is distributed on an "AS IS" BASIS, | ||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
version: 2 | ||
|
||
build: | ||
os: ubuntu-22.04 | ||
tools: | ||
python: "3.11" | ||
|
||
sphinx: | ||
configuration: docs/source/conf.py | ||
|
||
python: | ||
install: | ||
- requirements: docs/source/requirements.txt |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
# Copyright Jiaqi Liu | ||
# | ||
# Licensed under the Apache License, Version 2.0 (the "License"); | ||
# you may not use this file except in compliance with the License. | ||
# You may obtain a copy of the License at | ||
# | ||
# http://www.apache.org/licenses/LICENSE-2.0 | ||
# | ||
# Unless required by applicable law or agreed to in writing, software | ||
# distributed under the License is distributed on an "AS IS" BASIS, | ||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
|
||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = source | ||
BUILDDIR = build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=source | ||
set BUILDDIR=build | ||
|
||
if "%1" == "" goto help | ||
|
||
%SPHINXBUILD% >NUL 2>NUL | ||
if errorlevel 9009 ( | ||
echo. | ||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx | ||
echo.installed, then set the SPHINXBUILD environment variable to point | ||
echo.to the full path of the 'sphinx-build' executable. Alternatively you | ||
echo.may add the Sphinx directory to PATH. | ||
echo. | ||
echo.If you don't have Sphinx installed, grab it from | ||
echo.http://sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,96 @@ | ||
# Configuration file for the Sphinx documentation builder. | ||
# | ||
# This file only contains a selection of the most common options. For a full | ||
# list see the documentation: | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html | ||
|
||
# -- Path setup -------------------------------------------------------------- | ||
|
||
# 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. | ||
# | ||
import os | ||
import sys | ||
sys.path.insert(0, os.path.abspath('../../')) | ||
|
||
|
||
# -- Project information ----------------------------------------------------- | ||
|
||
project = 'screwdriver-cd-python-sdk' | ||
copyright = '2024, Jiaqi Liu' | ||
author = 'Jiaqi Liu' | ||
|
||
# The full version, including alpha/beta/rc tags | ||
release = '0.1.0' | ||
|
||
|
||
# -- General configuration --------------------------------------------------- | ||
|
||
# Add any Sphinx extension module names here, as strings. They can be | ||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom | ||
# ones. | ||
extensions = [ | ||
'sphinx.ext.autodoc', | ||
'hoverxref.extension', | ||
'notfound.extension', | ||
'sphinx.ext.coverage', | ||
'sphinx.ext.intersphinx', | ||
'sphinx.ext.viewcode', | ||
"sphinx.ext.graphviz", | ||
"pyan.sphinx" | ||
] | ||
|
||
# add graphviz options | ||
graphviz_output_format = "svg" | ||
|
||
# Add any paths that contain templates here, relative to this directory. | ||
templates_path = ['_templates'] | ||
|
||
# List of patterns, relative to source directory, that match files and | ||
# directories to ignore when looking for source files. | ||
# This pattern also affects html_static_path and html_extra_path. | ||
exclude_patterns = [] | ||
|
||
|
||
# -- Options for HTML output ------------------------------------------------- | ||
|
||
# The theme to use for HTML and HTML Help pages. See the documentation for | ||
# a list of builtin themes. | ||
# | ||
html_theme = 'sphinx_rtd_theme' | ||
|
||
# Add any paths that contain custom static files (such as style sheets) here, | ||
# relative to this directory. They are copied after the builtin static files, | ||
# so a file named "default.css" will overwrite the builtin "default.css". | ||
html_static_path = ['_static'] | ||
|
||
intersphinx_mapping = { | ||
'attrs': ('https://www.attrs.org/en/stable/', None), | ||
'coverage': ('https://coverage.readthedocs.io/en/stable', None), | ||
'cryptography': ('https://cryptography.io/en/latest/', None), | ||
'cssselect': ('https://cssselect.readthedocs.io/en/latest', None), | ||
'itemloaders': ('https://itemloaders.readthedocs.io/en/latest/', None), | ||
'pytest': ('https://docs.pytest.org/en/latest', None), | ||
'python': ('https://docs.python.org/3', None), | ||
'sphinx': ('https://www.sphinx-doc.org/en/master', None), | ||
'tox': ('https://tox.wiki/en/latest/', None), | ||
'twisted': ('https://docs.twisted.org/en/stable/', None), | ||
'twistedapi': ('https://docs.twisted.org/en/stable/api/', None), | ||
'w3lib': ('https://w3lib.readthedocs.io/en/latest', None), | ||
} | ||
intersphinx_disabled_reftypes = [] | ||
|
||
hoverxref_auto_ref = True | ||
hoverxref_role_types = { | ||
"class": "tooltip", | ||
"command": "tooltip", | ||
"confval": "tooltip", | ||
"hoverxref": "tooltip", | ||
"mod": "tooltip", | ||
"ref": "tooltip", | ||
"reqmeta": "tooltip", | ||
"setting": "tooltip", | ||
"signal": "tooltip", | ||
} | ||
hoverxref_roles = ['command', 'reqmeta', 'setting', 'signal'] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,79 @@ | ||
.. _faq: | ||
|
||
========================== | ||
Frequently Asked Questions | ||
========================== | ||
|
||
|
||
Python Sphinx Autodoc Is Not Rendering on readthedocs | ||
===================================================== | ||
|
||
The project's dependencies are not specified on RTD, but instead have installed the dependencies locally. We can verify | ||
this in the `build log <https://readthedocs.org/api/v2/build/17857935.txt>`_. Visit the project's Builds, click a build, | ||
and click "view raw":: | ||
|
||
WARNING: autodoc: failed to import module 'rnn' from module 'screwdriver_cd_python_sdk'; the following exception was raised: | ||
No module named 'matplotlib' | ||
|
||
To remedy the situation, we must specify that the project's dependencies to be installed. See | ||
`Specifying Dependencies <https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html>`_. | ||
|
||
|
||
Generate Sphinx Documentation Locally | ||
===================================== | ||
|
||
This site is auto-generated using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ with the following command in venv:: | ||
|
||
cd /path/to/screwdriver-cd-python-sdk/ | ||
python3 -m venv venv | ||
source venv/bin/activate | ||
pip3 install . | ||
pip3 install -r docs/source/requirements.txt | ||
sphinx-build -a -b html docs/source/ /path/to/html/output/dir | ||
deactivate | ||
|
||
.. NOTE:: | ||
The command above works for Linux/UNIX systems. Some commands will | ||
`differ on Windows OS <https://realpython.com/python-virtual-environments-a-primer/>`_ | ||
|
||
|
||
Install SDK from Source Locally | ||
=============================== | ||
|
||
We recommend creating a virtualenv for your application and activate it | ||
|
||
Navigate to the ``screwdriver-cd-python-sdk`` root directory and run:: | ||
|
||
pip3 install -e . | ||
|
||
For more general information, please refer to the | ||
`Hitchhiker's Guide to Python <https://docs.python-guide.org/writing/structure/#structuring-your-project>`_: "Structuring Your Project". | ||
|
||
|
||
"module 'collections' has no attribute 'Callable' Error When Running nosetests | ||
============================================================================== | ||
|
||
First, uninstall nose with the following command:: | ||
|
||
pip3 uninstall -y nose | ||
|
||
Second, reinstall nose but with ``--nobinaries`` flag:: | ||
|
||
pip3 install -U nose --no-binary :all: | ||
|
||
Why does this work? At the time of this writing the binary generated by nose was likely generated with a version of | ||
Python 3.4 or older. This command forces to rebuild from source. | ||
|
||
|
||
No module named 'pytest' while Running Test Directly in PyCharm | ||
=============================================================== | ||
|
||
"Right-click" run a ``test_**.py`` file results in:: | ||
|
||
Traceback (most recent call last): | ||
File "/Applications/PyCharm CE.app/Contents/plugins/python-ce/helpers/pycharm/_jb_pytest_runner.py", line 5, in <module> | ||
import pytest | ||
ModuleNotFoundError: No module named 'pytest' | ||
|
||
The solution is going to '**Settings** -> **Tools** -> **Python Integrated Tools**' and scroll down to where it says | ||
`pytest not found` and there is a **FIX** button. Clicking on it and apply the settings shall resolve the problem |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
======================================= | ||
Screwdriver CD Python SDK Documentation | ||
======================================= | ||
|
||
Getting help | ||
============ | ||
|
||
Having trouble? We'd like to help! | ||
|
||
* Try the :doc:`FAQ <faq>` -- it's got answers to some common questions. | ||
* Looking for specific information? Try the :ref:`genindex` or :ref:`modindex`. | ||
* Report bugs with screwdriver-cd-python-sdk in our `issue tracker`_. | ||
* Join the Discord community `Screwdriver CD Discord`_. | ||
|
||
.. hint:: | ||
* Since methods with two underscores (`__`) cannot be tested due to the | ||
`name mangling <https://qubitpi.github.io/cpython/tutorial/classes.html#private-variables>`_. We require | ||
all private methods and attributes to be prefixed with **single underscore prefix (`_`) only** | ||
* The phrase "Chinese" used throughout this documentation referse to "**Simplified Chinese**", instead of | ||
"Traditional Chinese" | ||
|
||
First Steps | ||
=========== | ||
|
||
.. toctree:: | ||
:caption: First steps | ||
:hidden: | ||
|
||
intro/install | ||
|
||
:doc:`intro/install` | ||
Get screwdriver-cd-python-sdk installed on your computer. | ||
|
||
|
||
Usage | ||
===== | ||
|
||
.. toctree:: | ||
:maxdepth: 100 | ||
|
||
sdk | ||
|
||
.. _issue tracker: https://github.com/QubitPi/screwdriver-cd-python-sdk/issues | ||
.. _Screwdriver CD Discord: https://discord.com/widget?id=1210108895062659152&theme=dark |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
.. _intro-install: | ||
|
||
================== | ||
Installation guide | ||
================== | ||
|
||
|
||
Supported Python versions | ||
========================= | ||
|
||
The SDK has been tested with Python 3.10. It may work with older versions of Python but it is not guaranteed. | ||
|
||
|
||
Installing SDK | ||
============== | ||
|
||
If you are already familiar with installation of Python packages, we can install SDK and its dependencies from | ||
`PyPI <https://pypi.org/project/screwdriver-cd-python-sdk/>`_ with:: | ||
|
||
pip3 install screwdriver-cd-python-sdk | ||
|
||
We strongly recommend that you install SDK in :ref:`a dedicated virtualenv <intro-using-virtualenv>`, to avoid | ||
conflicting with your system packages. | ||
|
||
If you're using `Anaconda <https://docs.anaconda.com/anaconda/>`_ or | ||
`Miniconda <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`_, please allow me to | ||
apologize because I hate those two, so we won't install the package from there. | ||
|
||
|
||
Installing from Source | ||
====================== | ||
|
||
When we want to apply a bug fix quicly by installing SDK locally, we can use:: | ||
|
||
git clone https://github.com/QubitPi/screwdriver-cd-python-sdk.git | ||
cd screwdriver-cd-python-sdk | ||
pip3 install -e . | ||
|
||
|
||
.. _intro-using-virtualenv: | ||
|
||
Using a virtual environment (Recommended) | ||
----------------------------------------- | ||
|
||
We recommend installing SDK in a virtual environment on all platforms. | ||
|
||
Python packages can be installed either globally (a.k.a system wide), or in user-space. We do not recommend installing | ||
SDK system wide. Instead, we recommend installing SDK within a "virtual environment" (:mod:`venv`), | ||
which keep you from conflicting with already-installed Python system packages. | ||
|
||
See :ref:`tut-venv` on how to create your virtual environment. | ||
|
||
Once you have created a virtual environment, we can install SDK inside it with ``pip3``, just like any other | ||
Python package. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
sphinx==5.0.2 | ||
sphinx-hoverxref==1.1.1 | ||
sphinx-notfound-page==0.8 | ||
sphinx-rtd-theme==1.0.0 | ||
pycodestyle | ||
requests | ||
pyan3 |
Oops, something went wrong.