Skip to content

Commit 11ad06f

Browse files
IgnisDaIgnisDa
authored
Add documentation with Sphinx (mherrmann#42)
Thank you @IgnisDa!
1 parent 0d5d0ef commit 11ad06f

13 files changed

+245
-33
lines changed

‎.gitignore

Lines changed: 57 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,60 @@
1-
.idea/
2-
.DS_Store
3-
venv/
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
43
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
516
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
pip-wheel-metadata/
24+
share/python-wheels/
625
*.egg-info/
7-
dist/
26+
.installed.cfg
27+
*.egg
28+
MANIFEST
29+
30+
# Installer logs
31+
pip-log.txt
32+
pip-delete-this-directory.txt
33+
34+
# Translations
35+
*.mo
36+
*.pot
37+
38+
# Sphinx documentation
39+
docs/_build/
40+
docs/modules/
41+
42+
# Environments
43+
.env
44+
.venv
45+
env/
46+
venv/
47+
ENV/
48+
env.bak/
49+
venv.bak/
50+
51+
# Personal Files
52+
personal/
53+
sample-data/
54+
pyproject.toml
55+
poetry.lock
56+
57+
# IDE / Editor
58+
.idea
59+
.vscode
60+

‎README.md

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
[Selenium-python](https://selenium-python.readthedocs.io/) is great for web
44
automation. Helium makes it easier to use. For example:
55

6-
![Helium Demo](doc/helium-demo.gif)
6+
![Helium Demo](docs/helium-demo.gif)
77

88
Under the hood, Helium forwards each call to Selenium. The difference is that
99
Helium's API is much more high-level. In Selenium, you need to use HTML IDs,
@@ -28,28 +28,28 @@ So in other words, you don't lose anything by using Helium over pure Selenium.
2828
In addition to its more high-level API, Helium simplifies further tasks that are
2929
traditionally painful in Selenium:
3030

31-
* **Web driver management:** Helium ships with its own copies of ChromeDriver
32-
and geckodriver so you don't need to download and put them on your PATH.
33-
* **iFrames:** Unlike Selenium, Helium lets you interact with elements inside
34-
nested iFrames, without having to first "switch to" the iFrame.
35-
* **Window management.** Helium notices when popups open or close and focuses /
36-
defocuses them like a user would. You can also easily switch to a window by
37-
(parts of) its title. No more having to iterate over Selenium window handles.
38-
* **Implicit waits.** By default, if you try click on an element with Selenium
39-
and that element is not yet present on the page, your script fails. Helium by
40-
default waits up to 10 seconds for the element to appear.
41-
* **Explicit waits.** Helium gives you a much nicer API for waiting for a
42-
condition on the web page to become true. For example: To wait for an element
43-
to appear in Selenium, you would write:
44-
```python
45-
element = WebDriverWait(driver, 10).until(
46-
EC.presence_of_element_located((By.ID, "myDynamicElement"))
47-
)
48-
```
49-
With Helium, you can write:
50-
```python
51-
wait_until(Button('Download').exists)
52-
```
31+
- **Web driver management:** Helium ships with its own copies of ChromeDriver
32+
and geckodriver so you don't need to download and put them on your PATH.
33+
- **iFrames:** Unlike Selenium, Helium lets you interact with elements inside
34+
nested iFrames, without having to first "switch to" the iFrame.
35+
- **Window management.** Helium notices when popups open or close and focuses /
36+
defocuses them like a user would. You can also easily switch to a window by
37+
(parts of) its title. No more having to iterate over Selenium window handles.
38+
- **Implicit waits.** By default, if you try click on an element with Selenium
39+
and that element is not yet present on the page, your script fails. Helium by
40+
default waits up to 10 seconds for the element to appear.
41+
- **Explicit waits.** Helium gives you a much nicer API for waiting for a
42+
condition on the web page to become true. For example: To wait for an element
43+
to appear in Selenium, you would write:
44+
```python
45+
element = WebDriverWait(driver, 10).until(
46+
EC.presence_of_element_located((By.ID, "myDynamicElement"))
47+
)
48+
```
49+
With Helium, you can write:
50+
```python
51+
wait_until(Button('Download').exists)
52+
```
5353

5454
## Installation
5555

@@ -89,7 +89,7 @@ the animation at the top of this page (`from helium import *`, ...).
8989

9090
## Your first script
9191

92-
I've compiled a [cheatsheet](doc/Cheatsheet.md) that quickly teaches you all
92+
I've compiled a [cheatsheet](docs/cheatsheet.md) that quickly teaches you all
9393
you need to know to be productive with Helium.
9494

9595
## API Documentation
@@ -115,11 +115,11 @@ see [Contributing](#Contributing) below.
115115
I find Helium extremely useful in my own projects and feel it should be more
116116
widely known. Here's how you can help with this:
117117

118-
* Star this project on GitHub.
119-
* Tell your friends and colleagues about it.
120-
* [Share it on Twitter with one click](https://twitter.com/intent/tweet?text=I%20find%20Helium%20very%20useful%20for%20web%20automation%20with%20Python%3A%20https%3A//github.com/mherrmann/helium)
121-
* Share it on other social media
122-
* Write a blog post about Helium.
118+
- Star this project on GitHub.
119+
- Tell your friends and colleagues about it.
120+
- [Share it on Twitter with one click](https://twitter.com/intent/tweet?text=I%20find%20Helium%20very%20useful%20for%20web%20automation%20with%20Python%3A%20https%3A//github.com/mherrmann/helium)
121+
- Share it on other social media
122+
- Write a blog post about Helium.
123123

124124
With this, I think we can eventually make Helium the de-facto standard for web
125125
automation in Python.

‎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/README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Welcome to helium's documentation
2+
3+
The documentation is built using
4+
[sphinx](https://www.sphinx-doc.org/en/master/index.html) and the theme used is
5+
[sphinx-rtd-theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/).
6+
7+
## Setting up documentation locally
8+
9+
Ensure you have `python` and `pip` installed on your
10+
system and then run this command in the project root:
11+
12+
```bash
13+
pip install -r requirements-dev.txt
14+
make -C docs/ html
15+
```
16+
17+
This will install all development dependencies for the project and then build
18+
the documentation in HTML format in `docs/_build/` directory. Open
19+
`docs/_build/index.html` in your browser to see the documentation.

‎doc/Cheatsheet.md renamed to ‎docs/cheatsheet.md

File renamed without changes.

‎docs/conf.py

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import os
2+
import sys
3+
4+
sys.path.insert(0, os.path.abspath('..'))
5+
6+
7+
# -- Project information -----------------------------------------------------
8+
9+
project = 'helium'
10+
copyright = '2020, Michael Herrmann'
11+
author = 'Michael Herrmann'
12+
13+
# The full version, including alpha/beta/rc tags
14+
release = '3.0.6-SNAPSHOT'
15+
16+
17+
# -- General configuration ---------------------------------------------------
18+
19+
# Add any Sphinx extension module names here, as strings. They can be
20+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
21+
# ones.
22+
extensions = ['sphinx.ext.autodoc',
23+
'sphinx_rtd_theme', 'sphinx.ext.githubpages']
24+
25+
# Add any paths that contain templates here, relative to this directory.
26+
templates_path = ['_templates']
27+
28+
# List of patterns, relative to source directory, that match files and
29+
# directories to ignore when looking for source files.
30+
# This pattern also affects html_static_path and html_extra_path.
31+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
32+
33+
34+
# -- Options for HTML output -------------------------------------------------
35+
36+
# The theme to use for HTML and HTML Help pages. See the documentation for
37+
# a list of builtin themes.
38+
#
39+
html_theme = 'sphinx_rtd_theme'
40+
41+
# Add any paths that contain custom static files (such as style sheets) here,
42+
# relative to this directory. They are copied after the builtin static files,
43+
# so a file named "default.css" will overwrite the builtin "default.css".
44+
html_static_path = ['_static']
45+
46+
# autodoc_member_order = 'bysource'

‎docs/contributors.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Contributors to this project
2+
============================
3+
..
4+
Please use this format to add your contributions to this file
5+
`SocialUsernameName <Profile-Url>`_ (**Your Name**) - *Description of your contribution in a few words*
6+
7+
- `mherrmann <https://github.com/mherrmann>`_ (**Michael Herrmann**) - *Initial work*
8+
- `IgnisDa <https://github.com/IgnisDa>`_ (**Diptesh Choudhuri**) - *Added documentation*
9+

‎doc/helium-demo.gif renamed to ‎docs/helium-demo.gif

File renamed without changes.

‎docs/index.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Welcome to helium's documentation!
2+
==================================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
:caption: Contents:
7+
8+
main.rst
9+
contributors.rst
10+
11+
12+
13+
Indices and tables
14+
==================
15+
16+
* :ref:`genindex`
17+
* :ref:`modindex`
18+
* :ref:`search`

‎docs/main.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Helium's Public Functions
2+
=========================
3+
4+
.. automodule:: helium
5+
:members:

‎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

‎requirements-dev.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
-r requirements.txt
2+
psutil==5.6.6
3+
sphinx-rtd-theme==0.5.0
4+
sphinx==3.2.1
5+
urllib3==1.25.10

‎requirements.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
selenium==3.141.0
2+
urllib3==1.25.10

0 commit comments

Comments
 (0)