jepler/toga
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Restructured and improved documentation

Browse source 
* updated Makefile to:
  * create a virtualenv for the documentation (``make install``)
  * provide a ``make run`` command
  * provide a ``make spelling`` command
* added a requirements_docs.txt
* added a spelling_wordlist for special words
* corrected various spelling errors
* updated conf.py to use RTD theme for local building
* restyled documentation home page, added logo
* moved content into tutorial/how-to/reference/background sections as appropriate
* renamed "internals" to "project"
* added internal reference links
* suppressed orphan warning for numerous pages
* updated .gitignore for /docs/env
This commit is contained in:
Daniele Procida 2017-08-08 10:26:35 +10:00
parent 01429994c5
commit 96f383f086
77 changed files with 618 additions and 228 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -7,6 +7,7 @@ dist
build
_build
distribute-*
docs/env
local
.tox
node_modules

28
docs/Makefile
View file

@ -6,11 +6,15 @@ SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
SOURCEDIR = .
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
VENV = ../env/bin/activate
PORT = 8001
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
@ -18,6 +22,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " instal to create a virtualenv called 'env' in the docs directory"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@ -37,6 +42,7 @@ help:
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " run to start a local autoreloading webserver on port 8001"
clean:
-rm -rf $(BUILDDIR)/*
@ -151,3 +157,25 @@ doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
spelling:
. $(VENV); $(SPHINXBUILD) -b spelling . _build/spelling
@echo
@echo "Check finished. Wrong words can be found in " \
"build/spelling/output.txt."
install:
@echo "... setting up virtualenv"
virtualenv env
. $(VENV); pip install -r requirements_docs.txt
@echo "\n" \
"-------------------------------------------------------------------------------------------------- \n" \
"* watch, build and serve the documentation: make run \n" \
"* check spelling: make spelling \n" \
"\n" \
"enchant must be installed in order for pyenchant (and therefore spelling checks) to work. See \n" \
"http://docs.django-cms.org/en/latest/contributing/documentation.html#install-the-spelling-software \n" \
"-------------------------------------------------------------------------------------------------- \n" \
run:
. $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) build/html --host 0.0.0.0 --port $(PORT)

6
docs/topics/commands.rst → docs/background/commands.rst
View file

@ -42,7 +42,7 @@ classify and organize the commands in your application:
Commands may not use all the metadata - for example, on some platforms, menus
will contain icons; on other platforms, they won't. Toga will use the metadata
if it is provided, but ignore it (or subsitute an appropriate default) if it
if it is provided, but ignore it (or substitute an appropriate default) if it
isn't.
Commands can be enabled and disabled; if you disable a command, it will
@ -66,7 +66,7 @@ You can also define custom groups.
Example
~~~~~~~
The following is an example of using
The following is an example of using menus and commands::
import toga
@ -97,7 +97,7 @@ The following is an example of using
This code defines a command ``cmd1`` that will be placed in first section of
the "Stuff" group. It can be activated by pressing CTRL-k (or CMD-K on a Mac).
The definitions for ``cmd2``, ``cmd3``, and ``cmd4`` have been ommitted, but would
The definitions for ``cmd2``, ``cmd3``, and ``cmd4`` have been omitted, but would
follow a similar pattern.
It doesn't matter what order you add commands to the app - the group, section

12
docs/background/index.rst Normal file
View file

@ -0,0 +1,12 @@
.. _background:
=============
Background
=============
.. toctree::
:maxdepth: 1
philosophy
togas-and-yaks
commands

47
docs/philosophy.rst → docs/background/philosophy.rst
View file

@ -1,3 +1,5 @@
.. _philosophy:
=========
Why Toga?
=========
@ -17,7 +19,7 @@ end user with the mess.
It's easy to spot apps that have been built using themed widget sets - they're
the ones that don't behave quite like any other app. Widgets don't look
*quite* right, or there's a menu bar on a window in an OS X app. Themes can
get quite close - but there are always telltale signs.
get quite close - but there are always tell-tale signs.
On top of that, native widgets are always faster than a themed generic widget.
After all, you're using native system capability that has been tuned and
@ -80,46 +82,3 @@ for Windows, OS X and Linux. These days, mobile computing is much more
important. But despite this, there aren't many good options for Python
programming on mobile platforms, and cross-platform mobile coding is still
elusive. Toga aims to correct this.
So... why the name Toga?
========================
We all know the aphorism that `"When in Rome, do as the Romans do."`_
.. _"When in Rome, do as the Romans do.": http://en.wiktionary.org/wiki/when_in_Rome_do_as_the_Romans_do
So - what does a well dressed Roman wear? A toga, of course! And what does a
well dressed Python app wear? Toga!
So... why the yak mascot?
=========================
It's a reflection of the long running joke about `yak shaving`_ in computer
programming. The story originally comes from MIT, and is related to a
Ren and Stimpy episode; over the years, the story has evolved, and now goes
something like this:
You want to borrow your neighbours hose so you can wash your car. But you
remember that last week, you broke their rake, so you need to go to the
hardware store to buy a new one. But that means driving to the hardware
store, so you have to look for your keys. You eventually find your keys
inside a tear in a cushion - but you can't leave the cushion torn,
because the dog will destroy the cushion if they find a little tear. The
cushion needs a little more stuffing before it can be repaired, but it's
a special cushion filled with exotic Tibetan yak hair.
The next thing you know, you're standing on a hillside in Tibet shaving a
yak. And all you wanted to do was wash your car.
An easy to use widget toolkit is the yak standing in the way of progress of a
number of PyBee_ projects, and the original creator of Toga has been tinkering
with various widget toolkits for over 20 years, so the metaphor seemed
appropriate.
.. _yak shaving: http://en.wiktionary.org/wiki/yak_shaving
.. _PyBee: http://pybee.org
Let's get started!
==================
Enough theory (and bad puns...) - let's get started with your first Toga app!

43
docs/background/togas-and-yaks.rst Normal file
View file

@ -0,0 +1,43 @@
.. _togas-and-yaks:
========================
Why "Toga"? Why the Yak?
========================
So... why the name Toga?
========================
We all know the aphorism that `"When in Rome, do as the Romans do."`_
.. _"When in Rome, do as the Romans do.": http://en.wiktionary.org/wiki/when_in_Rome_do_as_the_Romans_do
So - what does a well dressed Roman wear? A toga, of course! And what does a
well dressed Python app wear? Toga!
So... why the yak mascot?
=========================
It's a reflection of the long running joke about `yak shaving`_ in computer
programming. The story originally comes from MIT, and is related to a
Ren and Stimpy episode; over the years, the story has evolved, and now goes
something like this:
You want to borrow your neighbors hose so you can wash your car. But you
remember that last week, you broke their rake, so you need to go to the
hardware store to buy a new one. But that means driving to the hardware
store, so you have to look for your keys. You eventually find your keys
inside a tear in a cushion - but you can't leave the cushion torn,
because the dog will destroy the cushion if they find a little tear. The
cushion needs a little more stuffing before it can be repaired, but it's
a special cushion filled with exotic Tibetan yak hair.
The next thing you know, you're standing on a hillside in Tibet shaving a
yak. And all you wanted to do was wash your car.
An easy to use widget toolkit is the yak standing in the way of progress of a
number of PyBee_ projects, and the original creator of Toga has been tinkering
with various widget toolkits for over 20 years, so the metaphor seemed
appropriate.
.. _yak shaving: http://en.wiktionary.org/wiki/yak_shaving
.. _PyBee: http://pybee.org

31
docs/conf.py
View file

@ -101,9 +101,17 @@ pygments_style = 'sphinx'
# -- 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 = 'default'
# on_rtd: whether we are on readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
try:
import sphinx_rtd_theme
except ModuleNotFoundError:
html_theme = 'default'
else:
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -122,7 +130,7 @@ html_theme = 'default'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
html_logo = "images/toga.png"
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
@ -259,3 +267,18 @@ texinfo_documents = [
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# -- Options for spelling -------------------------------------------
# Spelling check needs an additional module that is not installed by default.
# Add it only if spelling check is requested so docs can be generated without it.
if 'spelling' in sys.argv:
extensions.append("sphinxcontrib.spelling")
# Spelling language.
spelling_lang = 'en_US'
# Location of word list.
spelling_word_list_filename = 'spelling_wordlist'
spelling_ignore_pypi_package_names = True

13
docs/internals/contributing.rst → docs/how-to/contribute.rst
View file

@ -1,5 +1,8 @@
Contributing to Toga
====================
.. _contribute:
=========================
How to contribute to Toga
=========================
If you experience problems with Toga, `log them on GitHub`_. If you want to contribute code, please `fork the code`_ and `submit a pull request`_.
@ -9,10 +12,10 @@ If you experience problems with Toga, `log them on GitHub`_. If you want to cont
.. _submit a pull request: https://github.com/pybee/toga/pulls
Setting up your development environment
---------------------------------------
Set up your development environment
=======================================
The recommended way of setting up your development envrionment for Toga
The recommended way of setting up your development environment for Toga
is to install a virtual environment, install the required dependencies and
start coding. Assuming that you are using ``virtualenvwrapper``, you only have
to run::

24
docs/how-to/get-started.rst Normal file
View file

@ -0,0 +1,24 @@
.. _get-started:
==================
How to get started
==================
.. note:
If you're new to Toga, we recommend starting with the :ref:`tutorial`, which will
take you step-by-step through your first steps and introduce you to the important
concepts you need to become familiar with. If you prefer just to dive in, read on.
Quickstart
==========
Create a new virtualenv. In your virtualenv, install Toga, and then run it::
$ pip install toga-demo
$ toga-demo
This will pop up a GUI window showing the full range of widgets available
to an application using Toga.
Have fun, and see the :ref:`reference` to learn more about what's going on.

12
docs/how-to/index.rst Normal file
View file

@ -0,0 +1,12 @@
.. _how-to:
=============
How-to Guides
=============
.. toctree::
:maxdepth: 1
:glob:
Get started <get-started>
Contribute to Toga <contribute>

BIN
docs/images/toga.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 24 KiB

96
docs/index.rst
View file

@ -1,3 +1,30 @@
.. raw:: html
<style>
.row {clear: both}
.column img {border: 1px solid black;}
@media only screen and (min-width: 1000px),
only screen and (min-width: 500px) and (max-width: 768px){
.column {
padding-left: 5px;
padding-right: 5px;
float: left;
}
.column3 {
width: 33.3%;
}
.column2 {
width: 50%;
}
}
</style>
====
Toga
====
@ -9,39 +36,52 @@ Toga is available on Mac OS, Windows, Linux (GTK), and mobile platforms such as
.. figure:: tutorial/screenshots/tutorial-2.png
:align: center
:width: 300
:width: 500
Quickstart
==========
In your virtualenv, install Toga, and then run it::
.. rst-class:: row
$ pip install toga-demo
$ toga-demo
Table of contents
=================
This will pop up a GUI window showing the full range of widgets available
to an application using Toga.
.. rst-class:: clearfix row
Getting Started
---------------
.. rst-class:: column column2
To get started, you can dive into our :doc:`Tutorials </tutorial/index>` or check out the widget :doc:`Reference </reference/index>`.
Prerequisites
~~~~~~~~~~~~~
:ref:`Tutorial <tutorial>`
------------------------------
Toga has some minimum requirements:
Get started with a hands-on introduction to pytest for beginners
* If you're on OS X, you need to be on 10.7 (Lion) or newer.
.. rst-class:: column column2
* If you're on Linux, you need to have GTK+ 3.4 or later. This is the
version that ships with Ubuntu 12.04; you'll need to have the
``python3-gi`` package installed. If you want to use the WebView widget,
you'll also need to have WebKit, plus the GI bindings to WebKit
(``gir1.2-webkit-3.0``) installed.
If these requirements aren't met, Toga either won't work at all, or won't
have full functionality.
:ref:`How-to guides <how-to>`
-----------------------------
Guides and recipes for common problems and tasks
.. rst-class:: column column2
:ref:`Reference <reference>`
------------------------------
Technical reference - commands, modules, classes, methods
.. rst-class:: column column2
:ref:`Background <background>`
------------------------------
Explanation and discussion of key topics and concepts
.. rst-class:: clearfix row
Community
=========
@ -57,15 +97,15 @@ Toga is part of the `BeeWare suite`_. You can talk to the community through:
.. _@pybeeware on Twitter: https://twitter.com/pybeeware
.. _pybee/general on Gitter: https://gitter.im/pybee/general
Contents
========
.. toctree::
:maxdepth: 2
:glob:
:hidden:
:titlesonly:
philosophy
tutorial/index
topic/index
how-to/index
reference/index
internals/index
background/index
project/index

12
docs/internals/index.rst
View file

@ -1,12 +0,0 @@
==============
Toga internals
==============
.. toctree::
:maxdepth: 2
:glob:
contributing
releases
roadmap
platforms

12
docs/project/index.rst Normal file
View file

@ -0,0 +1,12 @@
.. _project:
=================
About the project
=================
.. toctree::
:maxdepth: 2
:glob:
releases
roadmap

0
docs/internals/releases.rst → docs/project/releases.rst
View file

10
docs/internals/roadmap.rst → docs/project/roadmap.rst
View file

@ -67,7 +67,7 @@ Inputs are mechanisms for displaying and editing input provided by the user.
- Cocoa: Done
- GTK+: Gtk.TreeView with a Gtk.ListStore
- iOS: UITableView
* Tree: A scrollable display of heirarchical data
* Tree: A scrollable display of hierarchical data
- Cocoa: Done
- GTK+: Gtk.TreeView with a Gtk.TreeStore
- iOS: UITableView with navigation
@ -82,14 +82,14 @@ Inputs are mechanisms for displaying and editing input provided by the user.
Views
~~~~~
Views are mechanisms for displaying rich content, usually in a readonly manner.
Views are mechanisms for displaying rich content, usually in a read-only manner.
* Separator - a visual separator; usually a faint line.
- Cocoa: NSSeparator
- GTK+:
- iOS:
* ProgressBar - A horizontal bar that displays progress, either progress
against a known value, or indeterminiate
against a known value, or indeterminate
- Cocoa: Done
- GTK+: Gtk.ProgressBar
- iOS: UIProgressView
@ -166,7 +166,7 @@ Containers are widgets that can contain other widgets.
- iOS: ?
* NavigationContainer - A container view that holds a navigable tree of subviews;
essentially a view that has a "back" button to return to the previous view
in a heirarchy. Example of use: Top level navigation in the OS X System
in a hierarchy. Example of use: Top level navigation in the OS X System
Preferences panel.
- Cocoa: No native control
- GTK+: No native control; Gtk.HeaderBar in 3.10+
@ -227,7 +227,7 @@ features.
* Easy handling of long running tasks - possibly using generators to yield
control back to the event loop.
* Notification when updates are available
* Easy Licening/registration of apps. Monetization is not a bad thing, and
* Easy Licensing/registration of apps. Monetization is not a bad thing, and
shouldn't be mutually exclusive with open source.
Platforms

61
docs/reference/index.rst
View file

@ -1,57 +1,12 @@
.. _reference:
================
Widget Reference
Reference
================
------------
Core Widgets
------------
.. toctree::
:maxdepth: 1
Toga includes a set of core widgets, that can be placed with a :doc:`Box </reference/widgets/box>` Container.
==================== ============================================================ ====================================== ===================================================================
Component Usage Purpose Class
==================== ============================================================ ====================================== ===================================================================
Application :doc:`Documentation </reference/widgets/app>` Primary host for UI components :mod:`toga.interface.app.App`
Box :doc:`Documentation </reference/widgets/box>` Container for components :mod:`toga.interface.widgets.box.Box`
Font :doc:`Documentation </reference/widgets/font>` Fonts :mod:`toga.interface.font.Font`
Widget :doc:`Documentation </reference/widgets/widget>` Base class for widgets :mod:`toga.interface.widgets.base.Widget`
Window :doc:`Documentation </reference/widgets/window>` Window object :mod:`toga.interface.window.Window`
==================== ============================================================ ====================================== ===================================================================
---------------
General widgets
---------------
==================== ============================================================ ====================================== ===================================================================
Component Usage Purpose Class
==================== ============================================================ ====================================== ===================================================================
Button :doc:`Documentation </reference/widgets/button>` Basic clickable button :mod:`toga.interface.widgets.button.Button`
Image View :doc:`Documentation </reference/widgets/imageview>` Image Viewer :mod:`toga.interface.widgets.imageview.ImageView`
Label :doc:`Documentation </reference/widgets/label>` Text label :mod:`toga.interface.widgets.label.Label`
Multiline Text Input :doc:`Documentation </reference/widgets/multilinetextinput>` Multi-line Text Input field :mod:`toga.interface.widgets.multilinetextinput.MultilineTextInput`
Number Input :doc:`Documentation </reference/widgets/numberinput>` Number Input field :mod:`toga.interface.widgets.numberinput.NumberInput`
Option Container :doc:`Documentation </reference/widgets/optioncontainer>` Option Container :mod:`toga.interface.widgets.optioncontainer.OptionContainer`
Progress Bar :doc:`Documentation </reference/widgets/progressbar>` Progress Bar :mod:`toga.interface.widgets.progressbar.ProgressBar`
Selection :doc:`Documentation </reference/widgets/selection>` Selection :mod:`toga.interface.widgets.selection.Selection`
Text Input :doc:`Documentation </reference/widgets/textinput>` Text Input field :mod:`toga.interface.widgets.textinput.TextInput`
Table :doc:`Documentation </reference/widgets/table>` Table of data :mod:`toga.interface.widgets.table.Table`
Tree :doc:`Documentation </reference/widgets/tree>` Tree of data :mod:`toga.interface.widgets.tree.Tree`
==================== ============================================================ ====================================== ===================================================================
--------------
Layout widgets
--------------
==================== ============================================================ ====================================== ===================================================================
Component Usage Purpose Class
==================== ============================================================ ====================================== ===================================================================
Scroll Container :doc:`Documentation </reference/widgets/scrollcontainer>` Scrollable Container :mod:`toga.interface.widgets.scrollcontainer.ScrollContainer`
Split Container :doc:`Documentation </reference/widgets/splitcontainer>` Split Container :mod:`toga.interface.widgets.splitcontainer.SplitContainer`
Web View :doc:`Documentation </reference/widgets/webview>` Web View :mod:`toga.interface.widgets.webview.WebView`
==================== ============================================================ ====================================== ===================================================================
-------------------
Supported Platforms
-------------------
.. include:: ../supported_platforms.rst
platforms
widgets
supported_widgets

10
docs/internals/platforms.rst → docs/reference/platforms.rst
View file

@ -1,6 +1,6 @@
=======================
Toga supported plaforms
=======================
========================
Toga supported platforms
========================
Official platform support
=========================
@ -11,7 +11,7 @@ Desktop platforms
OS X
~~~~
.. image:: screenshots/cocoa.png
.. image:: /reference/screenshots/cocoa.png
The backend for OS X is named `toga-cocoa`_. It supports OS X 10.7 (Lion)
and later. It is installed automatically on OS X machines (machines that
@ -26,7 +26,7 @@ The OS X backend has seen the most development to date.
Linux
~~~~~
.. image:: screenshots/gtk.png
.. image:: /reference/screenshots/gtk.png
The backend for Linux platforms is named `toga-gtk`_. It supports GTK+ 3.4
and later. It is installed automatically on Linux machines (machines that

0
docs/internals/screenshots/cocoa.png → docs/reference/screenshots/cocoa.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 78 KiB

After

Width:  |  Height:  |  Size: 78 KiB

0
docs/internals/screenshots/gtk.png → docs/reference/screenshots/gtk.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 53 KiB

4
docs/reference/supported_platforms/App.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Box.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Button.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Command.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/EXPANDING_SPACER.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+----------------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Font.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Icon.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Image.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+----+-------+

4
docs/reference/supported_platforms/ImageView.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+----+-------+

4
docs/reference/supported_platforms/Label.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/MainWindow.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+----------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/MultilineTextInput.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+------------------+----+-----+----+------+-----+----+-------+

4
docs/reference/supported_platforms/NumberInput.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+-----------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/OptionContainer.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/PasswordInput.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+-------------+----+-----+----+------+-----+----+-------+

4
docs/reference/supported_platforms/ProgressBar.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+-----------+----+-----+----+------+-----+----+-------+

4
docs/reference/supported_platforms/SEPARATOR.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/SPACER.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/ScrollContainer.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Selection.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/SplitContainer.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+--------------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/TIBERIUS_ICON.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+-------------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Table.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/TextInput.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Tree.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/WebView.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

4
docs/reference/supported_platforms/Window.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
.. table::
+---------+-----+-----+----+------+-----+-----+-------+

6
docs/supported_platforms.rst → docs/reference/supported_widgets.rst
View file

@ -1,3 +1,9 @@
.. _supported-widgets:
==============================
Supported widgets by platform
==============================
.. table::
+-------------------------------------------------------------------+-----+-----+----+------+-----+-----+-------+

53
docs/reference/widgets.rst Normal file
View file

@ -0,0 +1,53 @@
.. _widget-reference:
================
Widget Reference
================
------------
Core Widgets
------------
Toga includes a set of core widgets, that can be placed with a :doc:`Box </reference/widgets/box>` Container.
==================== ============================================================ ====================================== ===================================================================
Component Usage Purpose Class
==================== ============================================================ ====================================== ===================================================================
Application :doc:`Documentation </reference/widgets/app>` Primary host for UI components :mod:`toga.interface.app.App`
Box :doc:`Documentation </reference/widgets/box>` Container for components :mod:`toga.interface.widgets.box.Box`
Font :doc:`Documentation </reference/widgets/font>` Fonts :mod:`toga.interface.font.Font`
Widget :doc:`Documentation </reference/widgets/widget>` Base class for widgets :mod:`toga.interface.widgets.base.Widget`
Window :doc:`Documentation </reference/widgets/window>` Window object :mod:`toga.interface.window.Window`
==================== ============================================================ ====================================== ===================================================================
---------------
General widgets
---------------
==================== ============================================================ ====================================== ===================================================================
Component Usage Purpose Class
==================== ============================================================ ====================================== ===================================================================
Button :doc:`Documentation </reference/widgets/button>` Basic clickable button :mod:`toga.interface.widgets.button.Button`
Image View :doc:`Documentation </reference/widgets/imageview>` Image Viewer :mod:`toga.interface.widgets.imageview.ImageView`
Label :doc:`Documentation </reference/widgets/label>` Text label :mod:`toga.interface.widgets.label.Label`
Multiline Text Input :doc:`Documentation </reference/widgets/multilinetextinput>` Multi-line Text Input field :mod:`toga.interface.widgets.multilinetextinput.MultilineTextInput`
Number Input :doc:`Documentation </reference/widgets/numberinput>` Number Input field :mod:`toga.interface.widgets.numberinput.NumberInput`
Option Container :doc:`Documentation </reference/widgets/optioncontainer>` Option Container :mod:`toga.interface.widgets.optioncontainer.OptionContainer`
Progress Bar :doc:`Documentation </reference/widgets/progressbar>` Progress Bar :mod:`toga.interface.widgets.progressbar.ProgressBar`
Selection :doc:`Documentation </reference/widgets/selection>` Selection :mod:`toga.interface.widgets.selection.Selection`
Text Input :doc:`Documentation </reference/widgets/textinput>` Text Input field :mod:`toga.interface.widgets.textinput.TextInput`
Table :doc:`Documentation </reference/widgets/table>` Table of data :mod:`toga.interface.widgets.table.Table`
Tree :doc:`Documentation </reference/widgets/tree>` Tree of data :mod:`toga.interface.widgets.tree.Tree`
==================== ============================================================ ====================================== ===================================================================
--------------
Layout widgets
--------------
==================== ============================================================ ====================================== ===================================================================
Component Usage Purpose Class
==================== ============================================================ ====================================== ===================================================================
Scroll Container :doc:`Documentation </reference/widgets/scrollcontainer>` Scrollable Container :mod:`toga.interface.widgets.scrollcontainer.ScrollContainer`
Split Container :doc:`Documentation </reference/widgets/splitcontainer>` Split Container :mod:`toga.interface.widgets.splitcontainer.SplitContainer`
Web View :doc:`Documentation </reference/widgets/webview>` Web View :mod:`toga.interface.widgets.webview.WebView`
==================== ============================================================ ====================================== ===================================================================

4
docs/reference/widgets/app.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Application
===========

4
docs/reference/widgets/box.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Box
===

4
docs/reference/widgets/button.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Button
======

4
docs/reference/widgets/font.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Font
====

4
docs/reference/widgets/imageview.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Image View
==========

4
docs/reference/widgets/label.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Label
=====

4
docs/reference/widgets/multilinetextinput.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Multi-line text input
=====================

4
docs/reference/widgets/numberinput.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Number Input
============

4
docs/reference/widgets/optioncontainer.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Option Container
================

4
docs/reference/widgets/progressbar.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Progress Bar
============

4
docs/reference/widgets/scrollcontainer.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Scroll Container
================

4
docs/reference/widgets/selection.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Selection
=========

4
docs/reference/widgets/splitcontainer.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Split Container
===============

4
docs/reference/widgets/table.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Table
=====

4
docs/reference/widgets/textinput.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Text Input
==========

4
docs/reference/widgets/tree.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Tree
====

4
docs/reference/widgets/webview.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Web View
========

4
docs/reference/widgets/widget.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Widget
======

4
docs/reference/widgets/window.rst
View file

@ -1,3 +1,7 @@
:orphan:
.. warnings about this file not being included in any toctree will be suppressed by :orphan:
Window
======

5
docs/requirements_docs.txt Normal file
View file

@ -0,0 +1,5 @@
sphinx
sphinxcontrib-spelling
pyenchant
sphinx-autobuild
sphinx_rtd_theme

62
docs/spelling_wordlist Normal file
View file

@ -0,0 +1,62 @@
App
apps
backends
ButtonsType
checkbox
CheckButton
clickable
closable
ColorButton
ComboBox
CSS
Ctrl
django
FileChooserDialog
Flexbox
GMail
GStreamer
Gtk
gtk
HeaderBar
Helvetica
iframe
iOS
libwebkitgtktoolbars
ListStore
MessageDialog
MessageType
metapackage
minimizable
multiline
OpenStreetMap
org
pre
prepurposed
ProgressBar
Progressbar
pybee
Quickstart
Refactored
Ren
rtype
resizable
Roadmap
scrollers
slideout
Stimpy
subsitute
subviews
textarea
TextView
toolbar
Toolbars
toolbars
toolkits
TreeStore
TreeView
Ubuntu
Webkit
webkit
webkitgtk
WebView

13
docs/topics/index.rst
View file

@ -1,13 +0,0 @@
============
Topic Guides
============
The following are detailed guides on
.. toctree::
:maxdepth: 1
:glob:
commands

47
docs/tutorial/index.rst
View file

@ -1,28 +1,32 @@
.. _tutorial:
=========
Tutorials
=========
Tutorial 0
----------
.. toctree::
:maxdepth: 1
:titlesonly:
tutorial-0
tutorial-1
tutorial-2
tutorial-3
Tutorial 0 - your first Toga app
================================
In :doc:`tutorial-0`, you will discover how to create a basic app and have a simple :mod:`toga.interface.widgets.button.Button` widget to click.
.. figure:: screenshots/tutorial-0.png
:align: center
:width: 300
Tutorial 1
----------
Tutorial 1 - a slightly less toy example
========================================
In :doc:`tutorial-1`, you will discover how to capture basic user input using the :mod:`toga.interface.widgets.textinput.TextInput` widget
and control layout.
.. figure:: screenshots/tutorial-1.png
:align: center
:width: 300
Tutorial 2
----------
Tutorial 2 - you put the box inside another box...
==================================================
In :doc:`tutorial-2`, you will discover how to use the :mod:`toga.interface.widgets.splitcontainer.SplitContainer` widget to display
some components, a toolbar and a table.
@ -31,8 +35,8 @@ some components, a toolbar and a table.
:align: center
:width: 300
Tutorial 3
----------
Tutorial 3 - let's build a browser!
===================================
In :doc:`tutorial-3`, you will discover how to use the :mod:`toga.interface.widgets.webview.WebView` widget to display
a simple browser.
@ -42,14 +46,3 @@ a simple browser.
:width: 300
Index
-----
.. toctree::
:maxdepth: 2
:glob:
tutorial-0
tutorial-1
tutorial-2
tutorial-3

8
docs/tutorial/tutorial-0.rst
View file

@ -30,7 +30,7 @@ Here's a complete code listing for our "Hello world" app::
main().main_loop()
Lets walk through this one line at a time.
Let's walk through this one line at a time.
The code starts with imports. First, we import toga::
@ -138,10 +138,10 @@ environment`_ first, and installing toga in that virtual environment.
* If you want to use the WebView widget, you'll also need to
have WebKit, plus the GI bindings to WebKit installed.
* For Ubuntu that's provided by the libwebkitgtk-3.0-0 and
gir1.2-webkit-3.0 packages.
* For Ubuntu that's provided by the ``libwebkitgtk-3.0-0`` and
``gir1.2-webkit-3.0`` packages.
* For Fedora it's all provided in the webkitgtk3 package.
* For Fedora it's all provided in the ``webkitgtk3`` package.
If these requirements aren't met, Toga either won't work at all, or won't
have full functionality.

2
docs/tutorial/tutorial-1.rst
View file

@ -68,7 +68,7 @@ This example shows off the use of Flexbox in Toga's CSS styling. Flexbox is a
new layout scheme that is part of the CSS3 specification that corrects the
problems with the older box layout scheme in CSS2. Flexbox is not yet
universally available in all web browsers, but that doesn't matter for Toga -
Toga provides an implemention of the Flexbox layout scheme. `CSS-tricks
Toga provides an implementation of the Flexbox layout scheme. `CSS-tricks
provides a good tutorial on Flexbox`_ if you've never come across it before.
.. _CSS-tricks provides a good tutorial on Flexbox: https://css-tricks.com/snippets/css/a-guide-to-flexbox/

2
docs/tutorial/tutorial-2.rst
View file

@ -12,7 +12,7 @@ Cascading Style Sheets, (CSS).
If you've done any design for the web, you will have come across CSS before as
the mechanism that you use to lay out HTML on a web page. Although this is the
reason CSS was developed, CSS itself is a general set of rules for laying out
any "boxes" that are structured in a tree-like heirarchy. GUI widgets are an
any "boxes" that are structured in a tree-like hierarchy. GUI widgets are an
example of one such structure.
To see how this works in practice, lets look at a more complex example,

4
src/core/toga/interface/app.py
View file

@ -11,7 +11,7 @@ class App:
When you create an App you need to provide it a name, an id for uniqueness
(by convention, the identifier is a "reversed domain name".) and an
optional startup function which should run once the App has initialised.
optional startup function which should run once the App has initialized.
The startup function typically constructs some initial user interface.
Once the app is created you should invoke the main_loop() method, which
@ -74,7 +74,7 @@ class App:
'''
The identifier for the app.
This is the reversed domain name, often used for targetting resources, etc.
This is the reversed domain name, often used for targeting resources, etc.
:rtype: ``str``
'''

2
src/core/toga/interface/widgets/button.py
View file

@ -84,7 +84,7 @@ class Button(Widget):
Indicates whether the button can be pressed by the user.
:returns: Button status. Default is True.
:rtype: ``Bool`
:rtype: ``Bool``
"""
return self._enabled