Skip to content

Commit 817d04d

Browse files
gnikonorovgnikonorov
authored
Move documentation to read the docs (#402)
* first pass at moving docs to read the docs * migrate to readthedocs * Fix broken development link in README * Use better build command and some stylistic touchups * Add development section on writing docs * undo changes to documentation not in readthedocs
1 parent ba4f154 commit 817d04d

File tree

10 files changed

+562
-1
lines changed

10 files changed

+562
-1
lines changed

‎.github/workflows/actions.yml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,21 @@ on:
1616
- cron: 1 0 * * * # Run daily at 0:01 UTC
1717

1818
jobs:
19+
build_docs:
20+
name: Build Docs
21+
runs-on: ubuntu-18.04
22+
steps:
23+
- uses: actions/checkout@master
24+
- name: Set up Python
25+
uses: actions/setup-python@v2
26+
with:
27+
python-version: 3.6
28+
- name: Install tox
29+
run: |
30+
python -m pip install --upgrade tox
31+
- name: Build docs with tox
32+
run: |
33+
python -m tox -e docs
1934
build_python:
2035
name: ${{ matrix.name }}
2136
runs-on: ${{ matrix.os }}

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,6 @@ Pipfile.lock
4848

4949
# tox folders
5050
.tox
51+
52+
# sphinx/read the docs
53+
docs/_build/

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
# -- Path setup --------------------------------------------------------------
7+
# If extensions (or modules to document with autodoc) are in another directory,
8+
# add these directories to sys.path here. If the directory is relative to the
9+
# documentation root, use os.path.abspath to make it absolute, like shown here.
10+
#
11+
# import os
12+
# import sys
13+
# sys.path.insert(0, os.path.abspath('.'))
14+
# -- Project information -----------------------------------------------------
15+
16+
project = "pytest-html"
17+
copyright = "2020, Dave Hunt" # noqa: A001
18+
author = "Dave Hunt"
19+
20+
21+
# -- General configuration ---------------------------------------------------
22+
23+
# Add any Sphinx extension module names here, as strings. They can be
24+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
25+
# ones.
26+
extensions = []
27+
28+
# Add any paths that contain templates here, relative to this directory.
29+
templates_path = ["_templates"]
30+
31+
# List of patterns, relative to source directory, that match files and
32+
# directories to ignore when looking for source files.
33+
# This pattern also affects html_static_path and html_extra_path.
34+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
35+
36+
37+
# -- Options for HTML output -------------------------------------------------
38+
39+
# The theme to use for HTML and HTML Help pages. See the documentation for
40+
# a list of builtin themes.
41+
#
42+
html_theme = "alabaster"
43+
html_theme_options = {
44+
"github_user": "pytest-dev",
45+
"github_repo": "pytest-html",
46+
"github_banner": "true",
47+
"github_type": "star",
48+
}
49+
50+
# Add any paths that contain custom static files (such as style sheets) here,
51+
# relative to this directory. They are copied after the builtin static files,
52+
# so a file named "default.css" will overwrite the builtin "default.css".
53+
html_static_path = ["_static"]
54+
55+
# The master toctree document.
56+
master_doc = "index"

‎docs/development.rst

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
Development
2+
===========
3+
4+
To contribute to `pytest-html` you can use `Pipenv`_ to manage a python virtual environment and
5+
`pre-commit`_ to help you with styling and formatting.
6+
7+
To setup the virtual environment and pre-commit, run:
8+
9+
.. code-block:: bash
10+
11+
$ pipenv install --dev
12+
$ pipenv run pre-commit install
13+
14+
If you're not using `Pipenv`_, run the following to install `pre-commit`_:
15+
16+
.. code-block:: bash
17+
18+
$ pip install pre-commit
19+
$ pre-commit install
20+
21+
22+
Automated Testing
23+
-----------------
24+
25+
All pull requests and merges are tested in `GitHub Actions`_ which are defined inside ``.github`` folder.
26+
27+
To retrigger CI to run again for a pull request, you either use dropdown option, close and reopen pull-request
28+
or to just update the branch containing it.
29+
30+
You can do this with `git commit --allow-empty`
31+
32+
Running Tests
33+
-------------
34+
35+
Python
36+
~~~~~~
37+
38+
You will need `Tox`_ installed to run the tests against the supported Python versions. If you're using `Pipenv`_
39+
it will be installed for you.
40+
41+
With `Pipenv`_, run:
42+
43+
.. code-block:: bash
44+
45+
$ pipenv run tox
46+
47+
Otherwise, to install and run, do:
48+
49+
.. code-block:: bash
50+
51+
$ pip install tox
52+
$ tox
53+
54+
JavaScript
55+
~~~~~~~~~~
56+
57+
You will need `npm`_ installed to run the JavaScript tests. Internally, we use `Grunt`_ and `QUnit`_ to run the tests.
58+
59+
Once `npm`_ is installed, you can install all needed dependencies by running:
60+
61+
.. code-block:: bash
62+
63+
$ npm install
64+
65+
Run the following to execute the tests:
66+
67+
.. code-block:: bash
68+
69+
$ npm test
70+
71+
Documentation
72+
-------------
73+
74+
Documentation is hosted on `Read the Docs`_, and is written in `RST`_. Remember to add any new files to the :code:`toctree`
75+
section in :code:`index.rst`.
76+
77+
To build your documentation, run:
78+
79+
.. code-block:: bash
80+
81+
$ tox -e docs
82+
83+
You can then run a local webserver to verify your changes compiled correctly.
84+
85+
SASS/SCSS/CSS
86+
-------------
87+
88+
You will need `npm`_ installed to compile the CSS, which is generated via `SASS/SCSS`_.
89+
90+
Once `npm`_ is installed, you can install all needed dependencies by running:
91+
92+
.. code-block:: bash
93+
94+
$ npm install
95+
96+
Run the following to generate the CSS:
97+
98+
.. code-block:: bash
99+
100+
$ npm run build:css
101+
102+
Releasing a new version
103+
-----------------------
104+
105+
Follow these steps to release a new version of the project:
106+
107+
#. Update your local master with the upstream master (``git pull --rebase upstream master``)
108+
#. Create a new branch
109+
#. Update ``CHANGES.rst`` with the new version, today's date, and all changes/new features
110+
#. Commit and push the new branch and then create a new pull request
111+
#. Wait for tests and reviews and then merge the branch
112+
#. Once merged, update your local master again (``git pull --rebase upstream master``)
113+
#. Tag the release with the new release version (``git tag v<new tag>``)
114+
#. Push the tag (``git push upstream --tags``)
115+
#. Done. Check `Github Actions`_ for release progress.
116+
117+
.. _GitHub Actions: https://github.com/pytest-dev/pytest-html/actions
118+
.. _Grunt: https://gruntjs.com
119+
.. _npm: https://www.npmjs.com
120+
.. _Pipenv: https://pipenv.pypa.io/en/latest
121+
.. _pre-commit: https://pre-commit.com
122+
.. _QUnit: https://qunitjs.com
123+
.. _Read The Docs: https://readthedocs.com
124+
.. _RST: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
125+
.. _SASS/SCSS: https://sass-lang.com
126+
.. _Tox: https://tox.readthedocs.io

‎docs/index.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. pytest-html documentation master file, created by
2+
sphinx-quickstart on Sun Dec 6 20:48:43 2020.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
pytest-html
7+
===========
8+
9+
pytest-html is a plugin for `pytest`_ that generates a HTML report for test results.
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: Contents:
14+
15+
installing
16+
user_guide
17+
development
18+
19+
.. _pytest: http://pytest.org

‎docs/installing.rst

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Installation
2+
============
3+
4+
Requirements
5+
------------
6+
7+
pytest-html will work with Python >=3.6 or PyPy3.
8+
9+
Installing pytest-html
10+
----------------------
11+
12+
To install pytest-html using `pip`_:
13+
14+
.. code-block:: bash
15+
16+
$ pip install pytest-html
17+
18+
To install from source:
19+
20+
.. code-block:: bash
21+
22+
$ pip install -e .
23+
24+
.. _pip: https://pip.pypa.io/

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

0 commit comments

Comments
 (0)