Merge branch 'integrate-sphinx-manpages' into 'master'

Integrate sphinx manpages

See merge request poezio/poezio!141

3 files changed, 114 insertions, 73 deletions

diff --git a/CHANGELOG b/CHANGELOG
index 695972e9..1ea483e0 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -23,6 +23,8 @@ https://dev.louiz.org/projects/poezio/roadmap
 - Fix marquee and dice plugin to use newer Last Message Correction format.
 - Bookmarks tab properly displays bookmarks method (local/remote) and allows
   to switch between them again.
+- Updated manpages and added manpages built from the doc in the setup process.
+  Packagers need to run setup.py build_man to have them built.
 
 # Forgotten additions
 
diff --git a/data/poezio.1 b/data/poezio.1
index d54e991c..4e9fbf12 100644
--- a/data/poezio.1
+++ b/data/poezio.1
@@ -1,45 +1,48 @@
 .\" Copyright 2010 Le Coz Florent
 .\" This man page is distributed under the GPLv3 license.
 .\" See COPYING file
-.TH "Poezio" "1" "September 26, 2011" "Poezio dev team" ""
+.TH "Poezio" "1" "May 31, 2020" "Poezio dev team" ""
 .SH "NAME"
-Poezio \- a ncurses jabber client written in python3
+Poezio \- a ncurses jabber client written in python
 .SH "SYNOPSIS"
 .B poezio [\-f \fICONFIG_FILE\fR] [\-d \fIDEBUG_FILE\fR] [\-h]
 .SH "DESCRIPTION"
 .B Poezio
-is a console jabber (XMPP) client written in Python and using ncurses to draw its interface. It aims at being similar to the most famous IRC clients, like weechat or irssi. The keyboard shortcuts are inspired from emacs. For more information on XMPP see http://xmpp.org and on Poezio see https://poez.io
+is a console jabber (XMPP) client written in Python and using ncurses to draw its interface. It aims at being similar to the most famous IRC clients, like weechat or irssi. Some keyboard shortcuts are inspired from emacs. For more information on XMPP see http://xmpp.org and on Poezio see https://poez.io
 .PP
 .SH "OPTIONS"
 .TP
 \fB\-f\fR, \fB\-\-file \fICONFIG_FILE\fR
-Run poezio using \fICONFIG_FILE\fR as the config file instead of ~/.config/poezio/poezio.cfg
+Run poezio using \fICONFIG_FILE\fR as the config file instead of ~/.config/poezio/poezio.cfg.
 .TP
 \fB\-d\fR, \fB\-\-debug \fIDEBUG_FILE\fR
-Log debug from both poezio and SleekXMPP in \fIDEBUG_FILE\fR. Debug contains incoming and outgoing stanzas in addition to various message helping poezio's debugging.
+Log debug from both poezio and slixmpp in \fIDEBUG_FILE\fR. Debug contains incoming and outgoing stanzas in addition to various message helping poezio's debugging.
 .TP
-\fB\-h\fR
-Display an help message
+\fB\-c\fR, \fB\-\-check\-config\fR
+Display the list of modified/unmodified config options, with their changes from the default.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display the poezio help message.
+
+.SH "BASICS"
+
+The following sections will give you a short overview on how to use poezio. Poezio has many more options, commands and key bindings, please refer to \fIpoezio.cfg(7)\fR, \fIpoezio.commands(7)\fR, \fIpoezio.keys(7)\fR or the full documentation which should have been provided alongside the source code, or check it online at https://doc.poez.io/.
 
-.SH "TABS"
-A \fItab\fR, in Poezio, is the base structure of the interface. A tab may contains one or more \fIwindows\fR, and can be of different types:
+A \fItab\fR, in Poezio, is the base structure of the interface. A tab may contains one or more \fIwindows\fR, the main types are:
 .RS
 .TP 6
 .I Roster \fRtab
-It contains a list of your contacts on the left, as well as an info window on the right.
+It contains a browsable list of your contacts on the left, as well as an info window on the right.
 .TP
-.I MUC \fRtab
-MUC stands for "Multi-User Chat".
+.I Chatroom \fRtab
+This tab displays the contents of a multi-user chat.
 .TP
 .I Conversation \fRtab
 It is used for one-to-one communication, usually when using a real Jabber account.
-.TP
-.I Private \fRtab
-It is used to privately communicate with someone in a MUC.
 
 .SH "KEY BINDINGS"
 While most of the keyboard shortcuts are common to all types of tabs, some of them are tab-specific.
-.SS Text edition 
+.SS Text edition
 These shortcuts work in any kind of tab; most of them are identical to emacs' ones.
 .RS
 .TP 8
@@ -146,9 +149,6 @@ The opposite of \fI/accept\fR.
 .SS MUC-specific commands
 .RS
 .TP 5
-.B /recolor
-Change the color of the nicknames in the conversation. Useful when a few people are talking and their random color happen to be the same: using this command will let you differentiate them more easily.
-.TP
 .B /kick <user>
 Kick the specified user from the room.
 .TP
@@ -165,7 +165,7 @@ View or change the topic of the room.
 Talk privately with the specified participant.
 .TP
 .B /part
-Leave the current room. 
+Leave the current room.
 
 .SH "BUGS"
 Sure.
@@ -174,8 +174,8 @@ Sure.
 If you're using a terminal multiplexer such as \fIscreen\fR or \fItmux\fR, it may be setting $TERM to "screen", which breaks 256-color support. Consider setting your $TERM to something like "screen-256color".
 
 .SH "FEEDBACK"
-You are encouraged to report bugs or feature requests on https://dev.louiz.org/projects/poezio.
-You can also find us on the Jabber chatroom poezio@muc.poez.io
+You are encouraged to report bugs or feature requests on https://lab.louiz.org/poezio/poezio.
+You can also find us on the Jabber chatroom xmpp:poezio@muc.poez.io?join
 
 .SH "AUTHORS"
 Written by Florent Le Coz <louiz@louiz.org>
diff --git a/setup.py b/setup.py
index f54bd8d5..1e7dd8fc 100755
--- a/setup.py
+++ b/setup.py
@@ -1,15 +1,21 @@
 #!/usr/bin/env python3
+import os
+import subprocess
+import sys
+from tempfile import TemporaryFile
 
 try:
     from setuptools import setup, Extension
 except ImportError:
     print('\nSetuptools was not found. Install setuptools for python 3.\n')
-    import sys
     sys.exit(1)
 
-import os
-import subprocess
-from tempfile import TemporaryFile
+cmdclass = {}
+try:
+    from sphinx.setup_command import BuildDoc
+    cmdclass = {'build_man': BuildDoc}
+except ImportError:
+    print('\nSphinx not found, the build_man command will be unavailable.\n')
 
 current_dir = os.path.dirname(__file__)
 
@@ -57,8 +63,30 @@ def check_include(library_name, header):
             print('%s headers not found.' % library_name)
             return False
 
+def sphinx_man():
+    expected_sphinx_files = [
+        'build/sphinx/man/poezio.cfg.7',
+        'build/sphinx/man/poezio.keys.7',
+        'build/sphinx/man/poezio.commands.7'
+    ]
+    found = []
+    for item in expected_sphinx_files:
+        if os.path.exists(item):
+            found.append(item)
+    if found:
+        return [('share/man/man7/', found)]
+    return []
+
+
+sphinx_files_found = sphinx_man()
+if not sphinx_files_found:
+    print(
+        '\nSphinx-built manpages not found. Only the '
+        'short handwritten manpages will be installed\n'
+    )
+
+
 if not check_include('python3', 'Python.h'):
-    import sys
     sys.exit(2)
 
 module_poopt = Extension('poezio.poopt',
@@ -88,52 +116,63 @@ else:
 with open('README.rst', encoding='utf-8') as readme_fd:
     LONG_DESCRIPTION = readme_fd.read()
 
-setup(name="poezio",
-      version="0.14" + version,
-      description="A console XMPP client",
-      long_description=LONG_DESCRIPTION,
-      ext_modules=[module_poopt],
-      url='https://poez.io/',
-      license='zlib',
-      download_url='https://dev.louiz.org/projects/poezio/files',
-
-      author='Florent Le Coz',
-      author_email='louiz@louiz.org',
-
-      maintainer='Mathieu Pasquet',
-      maintainer_email='mathieui@mathieui.net',
-
-      classifiers=['Development Status :: 5 - Production/Stable',
-                   'Topic :: Communications :: Chat',
-                   'Topic :: Internet :: XMPP',
-                   'Environment :: Console :: Curses',
-                   'Intended Audience :: End Users/Desktop',
-                   'License :: OSI Approved :: zlib/libpng License',
-                   'Natural Language :: English',
-                   'Operating System :: Unix',
-                   'Programming Language :: Python :: 3.8',
-                   'Programming Language :: Python :: 3.7',
-                   'Programming Language :: Python :: 3 :: Only'],
-      keywords=['jabber', 'xmpp', 'client', 'chat', 'im', 'console'],
-      packages=['poezio', 'poezio.core', 'poezio.tabs', 'poezio.windows',
-                'poezio.ui', 'poezio_plugins', 'poezio_themes'],
-      package_dir={'poezio': 'poezio',
-                   'poezio_plugins': 'plugins',
-                   'poezio_themes': 'data/themes'},
-      package_data={'poezio': ['default_config.cfg']},
-      scripts=['scripts/poezio_logs'],
-      entry_points={'console_scripts': ['poezio = poezio.__main__:run']},
-      data_files=([('share/man/man1/', ['data/poezio.1',
-                                        'data/poezio_logs.1']),
-                   ('share/poezio/', ['README.rst', 'COPYING', 'CHANGELOG']),
-                   ('share/applications/', ['data/io.poez.Poezio.desktop']),
-                   ('share/metainfo/', ['data/io.poez.Poezio.appdata.xml'])]
-                  + find_doc('share/doc/poezio/source', 'source')
-                  + find_doc('share/doc/poezio/html', 'build/html')),
-      install_requires=['slixmpp>=1.5.2', 'aiodns', 'pyasn1_modules', 'pyasn1'],
-      extras_require={'OTR plugin': 'python-potr>=1.0',
-                      'Screen autoaway plugin': 'pyinotify==0.9.4',
-                      'Avoiding cython': 'cffi'})
+setup(
+    name="poezio",
+    version="0.14" + version,
+    description="A console XMPP client",
+    long_description=LONG_DESCRIPTION,
+    ext_modules=[module_poopt],
+    url='https://poez.io/',
+    license='zlib',
+    download_url='https://dev.louiz.org/projects/poezio/files',
+
+    author='Florent Le Coz',
+    author_email='louiz@louiz.org',
+
+    maintainer='Mathieu Pasquet',
+    maintainer_email='mathieui@mathieui.net',
+
+    classifiers=['Development Status :: 5 - Production/Stable',
+        'Topic :: Communications :: Chat',
+        'Topic :: Internet :: XMPP',
+        'Environment :: Console :: Curses',
+        'Intended Audience :: End Users/Desktop',
+        'License :: OSI Approved :: zlib/libpng License',
+        'Natural Language :: English',
+        'Operating System :: Unix',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python :: 3 :: Only'],
+    keywords=['jabber', 'xmpp', 'client', 'chat', 'im', 'console'],
+    packages=['poezio', 'poezio.core', 'poezio.tabs', 'poezio.windows',
+        'poezio.ui', 'poezio_plugins', 'poezio_themes'],
+    package_dir={'poezio': 'poezio',
+        'poezio_plugins': 'plugins',
+        'poezio_themes': 'data/themes'},
+    package_data={'poezio': ['default_config.cfg']},
+    scripts=['scripts/poezio_logs'],
+    entry_points={'console_scripts': ['poezio = poezio.__main__:run']},
+    data_files=([
+            ('share/man/man1/', ['data/poezio.1', 'data/poezio_logs.1']),
+            ('share/poezio/', ['README.rst', 'COPYING', 'CHANGELOG']),
+            ('share/applications/', ['data/io.poez.Poezio.desktop']),
+            ('share/metainfo/', ['data/io.poez.Poezio.appdata.xml'])
+        ]
+        + find_doc('share/doc/poezio/source', 'source')
+        + find_doc('share/doc/poezio/html', 'build/html')
+        + sphinx_files_found
+    ),
+    install_requires=['slixmpp>=1.5.2', 'aiodns', 'pyasn1_modules', 'pyasn1'],
+    extras_require={'OTR plugin': 'python-potr>=1.0',
+        'Screen autoaway plugin': 'pyinotify==0.9.4',
+        'Avoiding cython': 'cffi'},
+    cmdclass=cmdclass,
+    command_options={
+        'build_man' : {
+            'builder': ('setup.py', 'man'),
+        }
+    },
+)
 
 # Remove the link afterwards
 if (os.path.exists(os.path.join(current_dir, 'poezio', 'default_config.cfg')) and