Merge pull request #129 from MightyCreak/update-docs

Improve the documentation

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - main.py slimmed down by about 5000 lines
 - The new widgets.py is a bit fat though (~4000 lines)
+- Cleaned the README.md and moved the documentation to docs/
 
 ### Fixed
 - The intense code cleaning seems to have fixed a bug with the `-c` argument

README.md

@@ -18,17 +18,7 @@ Some key features of Diffuse:
 * Unlimited undo
 * Easy keyboard navigation
 
-## Requirements
+## Installation
-
-Diffuse is implemented entirely in Python and should run on any platform with
-Python and PyGObject.
-
-* Python >= 3.4
-* PyGObject >= 3.18
-
-## Users
-
-### Installing using Flatpak
 
 This is the easiest way to install Diffuse:
 
@@ -36,97 +26,10 @@ This is the easiest way to install Diffuse:
 flatpak install io.github.mightycreak.Diffuse
 ```
 
-## Translators
+## Documentation
 
-Please refer to the [translation documentation](po/README.md).
+For a more detailed documentation for users, translators and developers, see
-
+the [documentation](docs/).
-## Developers
-
-### Setup
-
-#### Run Diffuse from source
-
-To run Diffuse from the source code, type this:
-```sh
-python main.py
-```
-
-To debug with VS Code, open the directory in VS Code, place your breakpoints and hit F5.
-
-#### Build Diffuse
-
-To build Diffuse, type this:
-```sh
-python setup.py build
-```
-
-To run from the build, type this:
-```sh
-PYTHONPATH=build/lib ./build/scripts-3.7/diffuse
-```
-
-#### Install Diffuse locally
-
-Diffuse build system is meson.
-
-To install diffuse locally:
-
-```sh
-meson setup build
-cd build
-meson compile
-meson install # requires admin privileges
-```
-
-To uninstall diffuse afterwards:
-
-```sh
-sudo ninja uninstall -C build
-sudo rm -v /usr/local/share/locale/*/LC_MESSAGES/diffuse.mo
-```
-
-Meson allows to change the default installation directories, see
-[command-line documentation](https://mesonbuild.com/Commands.html#configure).
-
-### Installing on Windows
-
-The `windows-installer` directory contains scripts for building an installable
-package for Windows that includes all dependencies.
-
-Diffuse can be packaged as a portable application by copying the installation
-directory to a pen drive and creating a front end that sets the
-`XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables prior to launching
-Diffuse.  The `XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables
-indicate where Diffuse should store persistent settings (eg. the path to a
-writable directory on the pen drive).
-
-## Building and testing the Flatpak package
-
-To install Diffuse locally:
-
-```sh
-flatpak install runtime/org.gnome.Sdk/$(uname -p)/3.38
-flatpak-builder build-flatpak --user --install io.github.mightycreak.Diffuse.yml
-```
-
-To run Diffuse through Flatpak:
-
-```sh
-flatpak run io.github.mightycreak.Diffuse
-```
-
-To uninstall Diffuse:
-
-```sh
-flatpak remove io.github.mightycreak.Diffuse
-```
-
-## Help Documentation
-
-Diffuse's help documentation is written in the DocBook format and can be easily
-converted into other formats using XSLT stylesheets.  If the local help
-documentation or its browser are unavailable, Diffuse will attempt to display
-the on-line help documentation using a web browser.
 
 ## Licenses
 

docs/README.md

@@ -0,0 +1,9 @@
+# Diffuse documentation
+
+Welcome to Diffuse documentation!
+
+Here are the main sections:
+
+1. [Users](users.md)
+2. [Translators](translators.md)
+3. [Developers](developers.md)

docs/developers.md

@@ -0,0 +1,63 @@
+# Developers documentation
+
+## Setup on Linux
+
+### Build, test and install using Flatpak
+
+To install Diffuse locally:
+
+```sh
+flatpak install runtime/org.gnome.Sdk/$(uname -p)/3.38
+flatpak-builder build-flatpak --user --install io.github.mightycreak.Diffuse.yml
+```
+
+To run Diffuse through Flatpak:
+
+```sh
+flatpak run io.github.mightycreak.Diffuse
+```
+
+To uninstall Diffuse:
+
+```sh
+flatpak remove io.github.mightycreak.Diffuse
+```
+
+### Build, test and install using Meson
+
+Diffuse build system is meson.
+
+To install diffuse locally:
+
+```sh
+meson setup build
+cd build
+meson compile
+meson test
+meson install # requires admin privileges
+```
+
+To uninstall diffuse afterwards:
+
+```sh
+sudo ninja uninstall -C build
+sudo rm -v /usr/local/share/locale/*/LC_MESSAGES/diffuse.mo
+```
+
+Meson allows to change the default installation directories, see
+[command-line documentation](https://mesonbuild.com/Commands.html#configure).
+
+## Setup on Windows
+
+_Note:_ The Windows port is not maintained and would need some love.
+Contributions are very welcome! 😉
+
+The `windows-installer` directory contains scripts for building an installable
+package for Windows that includes all dependencies.
+
+Diffuse can be packaged as a portable application by copying the installation
+directory to a pen drive and creating a front end that sets the
+`XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables prior to launching
+Diffuse.  The `XDG_CONFIG_HOME` and `XDG_DATA_DIR` environment variables
+indicate where Diffuse should store persistent settings (eg. the path to a
+writable directory on the pen drive).

docs/translators.md

@@ -1,5 +1,4 @@
-User Interface
+# Translators documentation
-==============
 
 Below are basic instructions for adding and maintaining Gettext translations
 for Diffuse.  The installer will discover .po files in this directory and
@@ -9,8 +8,7 @@ The example commands below show how to create and manage the Japanese
 translations.  Replace all instances of "ja" with the code for the desired
 language.
 
-Create PO template
+## Create PO template
-------------------
 
 To create or update the PO template (`po/diffuse.pot`), use this command at the
 repo root:
@@ -19,8 +17,7 @@ repo root:
 xgettext -o po/diffuse.pot -f po/POTFILES.in
 ```
 
-Create a new translation
+## Create a new translation
-------------------------
 
 To create a new translation file, you'll need a PO template. If not already
 created, refer to previous section "Create PO template".
@@ -39,8 +36,7 @@ created, refer to previous section "Create PO template".
 [gedit]: https://www.flathub.org/apps/details/org.gnome.gedit
 [vim]: https://www.vim.org/
 
-Update a translation
+## Update a translation
---------------------
 
 Use `update-translations.py` to update one or more PO files.
 
@@ -57,8 +53,7 @@ This command also validate the files, so if you see a message saying "N
 untranslated messages", use the text editor of your choice to complete the
 translations.
 
-Validate a translation
+## Validate a translation
-----------------------
 
 Use `update-translations.py` to validate one or more PO files.
 
@@ -69,8 +64,9 @@ Command-line:
 ./update-translations.py --check-only ja.po ko.po
 ```
 
-System Integration
+## Windows-specific files
-==================
+
+### Installer
 
 Localized text for the Microsoft Windows installer is stored in separate ISL
 files. Copy the [English version][english-win-docs] and replace the text to the
@@ -78,12 +74,15 @@ right of each equal sign.
 
 [english-win-docs]: ../windows-installer/en.isl
 
-Documentation
+### DocBook
-=============
 
-Documentation is stored in DocBook format.  Start a new translation of the
+Diffuse's help documentation is written in the DocBook format and can be easily
-manual by copying the English version of the [DocBook manual][docbook-manual]
+converted into other formats using XSLT stylesheets. If the local help
-and then edit the contents.
+documentation or its browser are unavailable, Diffuse will attempt to display
+the on-line help documentation using a web browser.
+
+Start a new translation of the manual by copying the English version of the
+[DocBook manual][docbook-manual] and then edit the contents.
 
 The DocBook manual is converted to HTML for Windows and Unix man pages for
 POSIX platforms. The conversion tools insert some English text that gets

docs/users.md

@@ -0,0 +1,9 @@
+# Users documentation
+
+## Requirements
+
+Diffuse is implemented in Python and should run on any platform with Python and
+PyGObject.
+
+* Python >= 3.4
+* PyGObject >= 3.18