[RFC libinput] dox: switch to sphinx for the user-visible documentation
Sending this out as patch even though what really matters is the
output. Which is... here, tadaaa!
https://people.freedesktop.org/~whot/libinput-rtd/
Basically the motivation here is to make the user-visible documentation less
awful, especially because these days, 90% of the doc needs are by end users,
not the developers. The API itself is just fine in doxygen, but for prose
doxygen's "Related Pages" features is not perfect.
So I'm wondering if using RTD-style documentation is a better option here.
This patch is a more-or-less 1:1 conversion of the hand-written
documentation to use sphinx with the RTD theme. For a good chuckle, look at
the awk/sed script. (that script would go away anway after the one-time
conversion to an .rst source format).
This is not a final version, it needs massaging of the page hierarchy, right
now everything is dumped into the sidebar which is less than ideal. And of
course there are more corner cases that need manual correction.
The doxygen documentation is still built in full - this should be reduced to
just the API documentation where applicable. Some exceptions are present
there, e.g. seats.dox is handwritten but really more of a developer topic.
Biggest issue is likely to find that magic split between user docs and
developer API and where it applies, I'm sure there are bits that should
kinda be in both. Eventually I'm thinking to put the user documentation
top-level and the API documentation in /api. Resolving the various
libinput_foo() functions to point to doxygen is not trivial - you can't link
to doxygen functions directly without knowing the hash. So either we just
point to the api/index.html or we parse the doxygen xml output somehow.
But let's be honest, there are probably less than 50 people worldwide that
need to care about libinput's API. Giving everyone who's confused about
clickpad software button behaviour a link to the API call isn't really
helpful anyway.
Anyway, right now I'm mostly looking for general comments on whether this is
a good idea or a bad one, whichever comes first. I'm not planning to switch
everything to sphinx btw, too much work to go through every function and fix
it. The developer API stays on doxygen.
---
doc/conf.py.in| 166 ++
doc/meson.build | 101
doc/sed-script.sh | 68 +++
doc/toctree.in| 6 ++
4 files changed, 341 insertions(+)
create mode 100644 doc/conf.py.in
create mode 100755 doc/sed-script.sh
create mode 100644 doc/toctree.in
diff --git a/doc/conf.py.in b/doc/conf.py.in
new file mode 100644
index ..a3b54562
--- /dev/null
+++ b/doc/conf.py.in
@@ -0,0 +1,166 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/stable/config
+
+# -- 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 = '@PROJECT_NAME@'
+copyright = '2018'
+author = ''
+
+# The short X.Y version
+version = '@PROJECT_VERSION'
+# The full version, including alpha/beta/rc tags
+release = '@PROJECT_VERSION@'
+
+
+# -- General configuration ---
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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.mathjax',
+'sphinx.ext.graphviz',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# 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 = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML
Re: [PATCH wayland 1/2] gitlab-ci: Trigger site's project pipeline
On Wed, Jul 18, 2018 at 09:47:51AM +1000, Peter Hutterer wrote: > On Mon, Jul 16, 2018 at 02:08:34PM -0300, Matheus Santana wrote: > > For automatically building and publishing docs. > > > > It'll be necessary to > > > > 1. create a pipeline trigger for the [site's project][trigger] > > 2. create a variable within [wayland's CI][envar] whose key is > >WAYLAND_FREEDESKTOP_ORG_PIPELINE_TRIGGER_TOKEN and value is the token > >created in previous step > > > > Also see https://gitlab.freedesktop.org/wayland/wayland/issues/48 > > > > Signed-off-by: Matheus Santana > > > > [trigger]: > > https://gitlab.freedesktop.org/wayland/wayland.freedesktop.org/settings/ci_cd > > [envar]: https://gitlab.freedesktop.org/wayland/wayland/settings/ci_cd > > --- > > .gitlab-ci.yml | 10 +- > > 1 file changed, 9 insertions(+), 1 deletion(-) > > > > diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml > > index 2489665..c6840e6 100644 > > --- a/.gitlab-ci.yml > > +++ b/.gitlab-ci.yml > > @@ -2,6 +2,7 @@ image: debian:stretch > > > > stages: > >- build > > + - deploy > > > > before_script: > >- echo 'path-exclude=/usr/share/doc/*' > > > /etc/dpkg/dpkg.cfg.d/99-exclude-cruft > > @@ -10,7 +11,7 @@ before_script: > >- echo 'exit 101' >> /usr/sbin/policy-rc.d > >- chmod +x /usr/sbin/policy-rc.d > >- apt-get update > > - - apt-get -y --no-install-recommends install build-essential automake > > autoconf libtool pkg-config libexpat1-dev libffi-dev libxml2-dev doxygen > > graphviz xmlto xsltproc docbook-xsl > > + - apt-get -y --no-install-recommends install build-essential automake > > autoconf libtool pkg-config libexpat1-dev libffi-dev libxml2-dev doxygen > > graphviz xmlto xsltproc docbook-xsl curl ca-certificates > > > > build-native: > >stage: build > > @@ -34,3 +35,10 @@ build-native: > > - build-*/wayland*/_build/sub/*.log > > - build-*/*.log > > - prefix-* > > + > > +publish-docs: > > + stage: deploy > > + script: > > + - curl -X POST -F token=$WAYLAND_FREEDESKTOP_ORG_PIPELINE_TRIGGER_TOKEN > > -F ref=master > > https://gitlab.freedesktop.org/api/v4/projects/136/trigger/pipeline > > fwiw, check out the libinput .gitlab-ci.yml for how to use the project name > here instead of the number. Either will work though. You can also use > image: registry.freedesktop.org/libinput/libinput/jq:latest > that way you can skip the before_script stage and speed up everything > significantly > > > + only: > > + - master > > I'd prefer the more explicit: > only: > refs: > - master > > but afaict yours will work just fine. However, > you probably want this here: > >only: >variables: > - $CI_PROJECT_PATH == "wayland/wayland" > > otherwise your're trying to run the job on any push to wayland master in any > personal project. They won't have the token set and thus not do anything but > waste time. > > also add a single line > dependencies: > > to indicate you don't care about any dependencies from previous steps correction: this needs to be dependencies: [] to indicate an empty array. Cheers, Peter ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
[PATCH v6 wayland-protocols] text-input: Add v3 of the text-input protocol
From: Carlos Garnacho This new protocol description is a simplification over v2. - All pre-edit text styling is gone. - Pre-edit cursor can span characters. - No events regarding input panel (OSK) state nor covered rectangle. Compositors are still free to handle situations where the keyboard focus rectangle is covered by the input panel. - No set_preferred_language request for clients. - There is no event to send keysyms. Compositors can use wl_keyboard interface instead. - All state is double-buffered, with specified state. Signed-off-by: Dorota Czaplejewicz Signed-off-by: Carlos Garnacho --- Hi again, I'm removing the line about Unicode from the commit message. Thanks, Dorota Czaplejewicz Makefile.am| 1 + unstable/text-input/text-input-unstable-v3.xml | 374 + 2 files changed, 375 insertions(+) create mode 100644 unstable/text-input/text-input-unstable-v3.xml diff --git a/Makefile.am b/Makefile.am index 4b9a901..86d7ca9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -3,6 +3,7 @@ unstable_protocols = \ unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml \ unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml \ unstable/text-input/text-input-unstable-v1.xml \ + unstable/text-input/text-input-unstable-v3.xml \ unstable/input-method/input-method-unstable-v1.xml \ unstable/xdg-shell/xdg-shell-unstable-v5.xml \ unstable/xdg-shell/xdg-shell-unstable-v6.xml \ diff --git a/unstable/text-input/text-input-unstable-v3.xml b/unstable/text-input/text-input-unstable-v3.xml new file mode 100644 index 000..80058a5 --- /dev/null +++ b/unstable/text-input/text-input-unstable-v3.xml @@ -0,0 +1,374 @@ + + + + +Copyright © 2012, 2013 Intel Corporation +Copyright © 2015, 2016 Jan Arne Petersen +Copyright © 2017, 2018 Red Hat, Inc. +Copyright © 2018 Purism SPC + +Permission to use, copy, modify, distribute, and sell this +software and its documentation for any purpose is hereby granted +without fee, provided that the above copyright notice appear in +all copies and that both that copyright notice and this permission +notice appear in supporting documentation, and that the name of +the copyright holders not be used in advertising or publicity +pertaining to distribution of the software without specific, +written prior permission. The copyright holders make no +representations about the suitability of this software for any +purpose. It is provided "as is" without express or implied +warranty. + +THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS +SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND +FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY +SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN +AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF +THIS SOFTWARE. + + + + + The zwp_text_input_v3 interface represents text input and input methods + associated with a seat. It provides enter/leave events to follow the + text input focus for a seat. + + Requests are used to enable/disable the text-input object and set + state information like surrounding and selected text or the content type. + The information about the entered text is sent to the text-input object + via the preedit_string and commit_string events. + + Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices + must not point to middle bytes inside a code point: they must either + point to the first byte of a code point or to the end of the buffer. + Lengths must be measured between two valid indices. + + Focus moving throughout surfaces will result in the emission of + zwp_text_input_v3.enter and zwp_text_input_v3.leave events. The focused + surface must perform zwp_text_input_v3.enable and + zwp_text_input_v3.disable requests as the keyboard focus moves across + editable and non-editable elements of the UI. Those two requests are not + expected to be paired with each other, the compositor must be able to + handle consecutive series of the same request. + + State is sent by the state requests (set_surrounding_text, + set_content_type and set_cursor_rectangle) and a commit request. + After an enter event or disable request all state information is + invalidated and needs to be resent by the client. + + This protocol defines requests and events necessary for regular clients +
[PATCH v5 wayland-protocols] text-input: Add v3 of the text-input protocol
From: Carlos Garnacho This new protocol description is a simplification over v2. - All pre-edit text styling is gone. - Pre-edit cursor can span characters. - No events regarding input panel (OSK) state nor covered rectangle. Compositors are still free to handle situations where the keyboard focus rectangle is covered by the input panel. - No set_preferred_language request for clients. - There is no event to send keysyms. Compositors can use wl_keyboard interface instead. - All state is double-buffered, with specified state. - Use Unicode codepoints to measure strings. Signed-off-by: Dorota Czaplejewicz Signed-off-by: Carlos Garnacho --- Hi all, thanks for the feedback on the previous patch. The most controversial part was my switch from measuring bytes to code points when passing around Unicode strings. This v5 of the patch reverses that and we're in bytes land again. I hope that this version passes scrutiny and gets accepted to the Wayland family. Cheers, Dorota PS. Right now I'm working on getting wlroots and GTK to use this protocol. Makefile.am| 1 + unstable/text-input/text-input-unstable-v3.xml | 374 + 2 files changed, 375 insertions(+) create mode 100644 unstable/text-input/text-input-unstable-v3.xml diff --git a/Makefile.am b/Makefile.am index 4b9a901..86d7ca9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -3,6 +3,7 @@ unstable_protocols = \ unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml \ unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml \ unstable/text-input/text-input-unstable-v1.xml \ + unstable/text-input/text-input-unstable-v3.xml \ unstable/input-method/input-method-unstable-v1.xml \ unstable/xdg-shell/xdg-shell-unstable-v5.xml \ unstable/xdg-shell/xdg-shell-unstable-v6.xml \ diff --git a/unstable/text-input/text-input-unstable-v3.xml b/unstable/text-input/text-input-unstable-v3.xml new file mode 100644 index 000..80058a5 --- /dev/null +++ b/unstable/text-input/text-input-unstable-v3.xml @@ -0,0 +1,374 @@ + + + + +Copyright © 2012, 2013 Intel Corporation +Copyright © 2015, 2016 Jan Arne Petersen +Copyright © 2017, 2018 Red Hat, Inc. +Copyright © 2018 Purism SPC + +Permission to use, copy, modify, distribute, and sell this +software and its documentation for any purpose is hereby granted +without fee, provided that the above copyright notice appear in +all copies and that both that copyright notice and this permission +notice appear in supporting documentation, and that the name of +the copyright holders not be used in advertising or publicity +pertaining to distribution of the software without specific, +written prior permission. The copyright holders make no +representations about the suitability of this software for any +purpose. It is provided "as is" without express or implied +warranty. + +THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS +SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND +FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY +SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN +AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF +THIS SOFTWARE. + + + + + The zwp_text_input_v3 interface represents text input and input methods + associated with a seat. It provides enter/leave events to follow the + text input focus for a seat. + + Requests are used to enable/disable the text-input object and set + state information like surrounding and selected text or the content type. + The information about the entered text is sent to the text-input object + via the preedit_string and commit_string events. + + Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices + must not point to middle bytes inside a code point: they must either + point to the first byte of a code point or to the end of the buffer. + Lengths must be measured between two valid indices. + + Focus moving throughout surfaces will result in the emission of + zwp_text_input_v3.enter and zwp_text_input_v3.leave events. The focused + surface must perform zwp_text_input_v3.enable and + zwp_text_input_v3.disable requests as the keyboard focus moves across + editable and non-editable elements of the UI. Those two requests are not + expected to be paired with each other, the compositor must be able to + handle consecutive series of the same
Re: [PATCHv4 wayland-protocols] text-input: Add v3 of the text-input protocol
Hi Carlos, thanks for reviewing! On Tue, 17 Jul 2018 19:18:36 +0200 Carlos Garnacho wrote: > Hi!, > > (Way way late, trying to revive the conversation...) > > On Thu, May 3, 2018 at 9:22 PM, Dorota Czaplejewicz > wrote: > > On Thu, 3 May 2018 20:47:27 +0200 > > Silvan Jegen wrote: > > > >> Hi Dorota > >> > >> Some comments and typo fixes below. > >> > >> On Thu, May 03, 2018 at 05:41:21PM +0200, Dorota Czaplejewicz wrote: > >> > This new protocol description is a simplification over v2. > >> > > >> > - All pre-edit text styling is gone. > >> > - Pre-edit cursor can span characters. > >> > - No events regarding input panel (OSK) state nor covered rectangle. > >> > Compositors are still free to handle situations where the keyboard > >> > focus rectangle is covered by the input panel. > >> > - No set_preferred_language request for clients. > >> > - There is no event to send keysyms. Compositors can use wl_keyboard > >> > interface instead. > >> > - All state is double-buffered, with specified state. > >> > - Use Unicode codepoints to measure strings. > >> > > >> > Signed-off-by: Dorota Czaplejewicz > >> > Signed-off-by: Carlos Garnacho > >> > --- > >> > This is the next update coming from Purism to perfect the text input > >> > protocol. > >> > > >> > The following changes added on top of PATCHv3: > >> > > >> > - Fixed whitespaces. > >> > - Removed enable flags - the same information can be gathered from the > >> > first requests after enter. > >> > - Changed offsets inside UTF-8 strings to use Unicode character counts > >> > in order to remove the possibility of communicating invalid state. > >> > - Specified the exact lifetime of double-buffered state, and initial > >> > values. > >> > - Made changes requested by the IM double-buffered. > >> > > >> > Some questions remain open. One is: how to specify how much text to > >> > capture in set_surrounding_text, and how often to update? > > IMHO the only reason to state it here is that it's more likely that a > lazy implementation will try to squeeze a full book here, than eg. an > application setting an insanely long title. But certainly other > messages across protocols may hit this limit (the long title issue > wasn't made up :). > > As for how much, I think it ultimately depends on the IM behind. Text > correction probably just wants the current word, any sort of > prediction will probably require phrases to paragraphs, char > composition can probably do without. Sounds like this could be some > sort of hint, but I don't think IMs can tell you today how much text > do they want... > > >> > > >> > A possible change that I decided against for now is to replace > >> > enable/disable events by create/destroy of a new object, which would > >> > make more state lifetimes encoded in the protocol. > >> > > >> > After reading a blog post on fcitx [0], I got the impression that > >> > letting the compositor know some persistent ID of a text edit instance > >> > could be useful, however I'm not sure what the use cases are. > >> > > >> > As always, I'm happy to hear feedback. > >> > > >> > Cheers, > >> > Dorota Czaplejewicz > >> > > >> > [0] > >> > https://www.csslayer.info/wordpress/fcitx-dev/gaps-between-wayland-and-fcitx-or-all-input-methods/ > >> > > >> > Makefile.am| 1 + > >> > unstable/text-input/text-input-unstable-v3.xml | 362 > >> > + > >> > 2 files changed, 363 insertions(+) > >> > create mode 100644 unstable/text-input/text-input-unstable-v3.xml > >> > > >> > diff --git a/Makefile.am b/Makefile.am > >> > index 4b9a901..86d7ca9 100644 > >> > --- a/Makefile.am > >> > +++ b/Makefile.am > >> > @@ -3,6 +3,7 @@ unstable_protocols = > >> >\ > >> > unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml > >> >\ > >> > unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml > >> >\ > >> > unstable/text-input/text-input-unstable-v1.xml > >> >\ > >> > + unstable/text-input/text-input-unstable-v3.xml > >> >\ > >> > unstable/input-method/input-method-unstable-v1.xml > >> >\ > >> > unstable/xdg-shell/xdg-shell-unstable-v5.xml > >> >\ > >> > unstable/xdg-shell/xdg-shell-unstable-v6.xml > >> >\ > >> > diff --git a/unstable/text-input/text-input-unstable-v3.xml > >> > b/unstable/text-input/text-input-unstable-v3.xml > >> > new file mode 100644 > >> > index 000..ed5204f > >> > --- /dev/null > >> > +++ b/unstable/text-input/text-input-unstable-v3.xml > >> > @@ -0,0 +1,362 @@ > >> > + > >> > + > >> > + > >> > + > >> > +Copyright © 2012, 2013 Intel Corporation > >> > +Copyright © 2015, 2016 Jan Arne Petersen > >> > +Copyright © 2017, 2018 Red Hat, Inc. > >> > +Copyright © 2018 Purism SPC > >> > + >
