Skip to content

Commit c30d89b

Browse files
sebastiansam55sebastiansam55
committed
switch to sphinx-build
1 parent 817f149 commit c30d89b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+765
-8592
lines changed

‎.github/workflows/pages.yml

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Build Autokey pages
2+
on: [push, workflow_dispatch]
3+
4+
permissions:
5+
contents: read
6+
pages: write
7+
id-token: write
8+
9+
jobs:
10+
sphinx-build:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: checkout repo
14+
uses: actions/[email protected]
15+
- name: install git
16+
run: |
17+
sudo apt-get install git -y
18+
19+
- name: clone and install autokey
20+
run: |
21+
git clone https://github.com/autokey/autokey
22+
cd autokey
23+
pip install .
24+
- name: install sphinx
25+
run: pip install sphinx recommonmark sphinx-rtd-theme sphinx-epytext enum-tools[sphinx]
26+
- name: build sphinx site
27+
run: |
28+
mkdir docs
29+
sphinx-build -a -E -b html ./ docs
30+
- name: Upload artifact
31+
uses: actions/upload-pages-artifact@v1
32+
with:
33+
path: docs
34+
35+
deploy:
36+
environment:
37+
name: github-pages
38+
url: ${{ steps.deployment.outputs.page_url }}
39+
needs: sphinx-build
40+
runs-on: ubuntu-latest
41+
name: Deploy
42+
steps:
43+
- name: Deploy to GitHub Pages
44+
id: deployment
45+
uses: actions/deploy-pages@v1

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
_build/*
2+
_build/
3+
ak_temp/
4+
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)

‎README.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Autokey Documentation
2+
3+
Built using [sphinx]().
4+
5+
Uses the [sphinx autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) extension to automatically generate API documentation. This module imports the modules and reads the documentation for each function and generates the API documentation based on that.
6+
7+
Uses the [sphinx epytext]() extension to convert older style epydoc documentation format to sphinx readable.
8+
9+
I also have it set to use [recommonmark]() in case any one wants to use markdown really badly.
10+
11+
It also uses the default [sphinx.ext.viewcode](https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html) to insert links to the related source code.
12+
13+
14+
15+
16+
## Local testing
17+
You'll need the following python packages (and dependencies). From my command history getting it up and running;
18+
```
19+
git clone https://github.com/sebastiansam55/autokey-sphinx
20+
cd autokey-sphinx
21+
git clone https://github.com/autokey/autokey
22+
cd autokey
23+
pip install .
24+
cd ..
25+
pip install sphinx recommonmark sphinx-rtd-theme sphinx-epytext enum-tools[sphinx]
26+
# for first time installs you'll likely have to restart your shell for the sphinx-build command to be found.
27+
28+
# should be run from the base of this repository
29+
sphinx-build -a -E -b html . ./docs
30+
```
31+
32+
33+
## Github Actions
34+
Basic workflow:
35+
* Installs Git
36+
* Clones autokey/autokey (master branch)
37+
* Installs Autokey using `pip install .` in autokey repo
38+
* Installs sphinx
39+
* `pip install sphinx recommonmark sphinx-rtd-theme sphinx-epytext`
40+
* Builds sphinx site
41+
* `sphinx-build -a -E -b html ./ docs`
42+
* Uploads pages Artifact (docs output folder)
43+
* Deploys to Github Pages for this repository
44+
45+
46+
## TODO
47+
There is a plugin that supports versioned documentation, [sphinxcontrib-multiversion](https://github.com/Holzhaus/sphinx-multiversion) which seems to be decently well maintained.
48+
49+
Going forward we should use sphinx syntax in comments instead of older epytext.;
50+
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
51+
52+
For more information on the new comment markup.
53+
54+

‎api-objects.txt

Lines changed: 0 additions & 96 deletions
This file was deleted.

‎api.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Autokey API
2+
===========
3+
4+
Note that the `class` paths are not relevant to everyday autokey scripting. Generally speaking you can call all of these modules directly;
5+
::
6+
keyboard.send_keys("example document")
7+
clipboard.set_content("update clipboard")
8+
9+
10+
Is all that you need to call a method in the keyboard/clipboard API, note that you do not have to worry about import statements.
11+
12+
For the Qt/Gtk pages, these are abstracted, Autokey will select the UI framework most appropriate, you only need to reference these in your scripts as;
13+
::
14+
dialog.info_dialog("Info dialog", "Test info dialog")
15+
clipboard.set_content("clipboard content")
16+
17+
.. toctree::
18+
api/keyboard.rst
19+
api/mouse.rst
20+
api/store.rst
21+
api/qtdialog.rst
22+
api/qtclipboard.rst
23+
api/gtkdialog.rst
24+
api/gtkclipboard.rst
25+
api/system.rst
26+
api/window.rst
27+
api/engine.rst
28+
api/highlevel.rst
29+
api/common.rst
30+

‎api/common.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Common API
2+
==========
3+
4+
.. automodule:: autokey.scripting
5+
:no-members:
6+
.. autoclass:: ColourData
7+
:members:
8+
.. autoclass:: DialogData
9+
:members:

‎api/engine.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Engine API
2+
==========
3+
4+
.. automodule:: autokey.common
5+
:no-members:
6+
.. automodule:: autokey.gtkapp
7+
:no-members:
8+
.. automodule:: autokey.scripting
9+
:no-members:
10+
.. autoclass:: Engine
11+
:members:
12+
:exclude-members: Key, SendMode

‎api/gtkclipboard.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
GtkClipboard API
2+
================
3+
4+
.. autoclass:: autokey.scripting.clipboard_gtk.GtkClipboard
5+
:members:
6+
:exclude-members: app, clipBoard

‎api/gtkdialog.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
GtkDialog API
2+
=============
3+
4+
Known simply as ``dialog`` if you are using Gtk
5+
6+
.. autoclass:: autokey.scripting.dialog_gtk.GtkDialog
7+
:members:

‎api/highlevel.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
HighLevel API
2+
=============
3+
4+
.. automodule:: autokey.scripting.highlevel
5+
:no-members:
6+
.. autoclass:: PatternNotFound
7+
:members:
8+
.. autofunction:: visgrep
9+
.. autofunction:: get_png_dim
10+
.. autofunction:: mouse_move
11+
.. autofunction:: mouse_rmove
12+
.. autofunction:: mouse_click
13+
.. autofunction:: mouse_pos
14+
.. autofunction:: click_on_pat
15+
.. autofunction:: move_to_pat
16+
.. autofunction:: acknowledge_gnome_notification
17+
18+
19+
20+
21+
22+

‎api/keyboard.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Keyboard API
2+
============
3+
4+
.. automodule:: autokey.common
5+
:no-members:
6+
.. automodule:: autokey.gtkapp
7+
:no-members:
8+
.. automodule:: autokey.scripting
9+
:no-members:
10+
.. autoclass:: Keyboard
11+
:members:
12+
:exclude-members: mediator
13+
14+
Keys
15+
====
16+
17+
.. autoenum:: autokey.model.key.Key
18+
:members:

‎api/mouse.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Mouse API
2+
=========
3+
4+
.. automodule:: autokey.common
5+
:no-members:
6+
.. automodule:: autokey.gtkapp
7+
:no-members:
8+
.. automodule:: autokey.scripting
9+
:no-members:
10+
.. autoclass:: Mouse
11+
:members:
12+
13+
14+
Buttons
15+
=======
16+
17+
.. autoenum:: autokey.model.button.Button
18+
:members:

‎api/qtclipboard.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
QtClipboard API
2+
===============
3+
4+
.. autoclass:: autokey.scripting.clipboard_qt.QtClipboard
5+
:members:
6+
:exclude-members: app, clipBoard, sem, text

‎api/qtdialog.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
QtDialog API
2+
============
3+
4+
.. autoclass:: autokey.scripting.dialog_qt.QtDialog
5+
:members:

‎api/store.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Store API
2+
=========
3+
4+
.. automodule:: autokey.model.store
5+
:no-members:
6+
.. autoclass:: Store
7+
:members:
8+

‎api/system.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
System API
2+
==========
3+
4+
.. automodule:: autokey.common
5+
:no-members:
6+
.. automodule:: autokey.gtkapp
7+
:no-members:
8+
.. automodule:: autokey.scripting
9+
:no-members:
10+
.. autoclass:: System
11+
:members:

0 commit comments

Comments
 (0)