From d0fb098fe5037b27435a040e3ad83fec248d7597 Mon Sep 17 00:00:00 2001 From: Romain Failliot Date: Wed, 24 Nov 2021 12:26:26 -0500 Subject: [PATCH] Improve the documentation * Simplify the main README.md * Moved more detailed documentations into a new docs/ directory --- CHANGELOG.md | 1 + README.md | 105 ++-------------------------- docs/README.md | 9 +++ docs/developers.md | 63 +++++++++++++++++ po/README.md => docs/translators.md | 37 +++++----- docs/users.md | 9 +++ 6 files changed, 104 insertions(+), 120 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/developers.md rename po/README.md => docs/translators.md (75%) create mode 100644 docs/users.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5270eb1..91d7f69 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 21fb5eb..b2f1d72 100644 --- a/README.md +++ b/README.md @@ -18,17 +18,7 @@ Some key features of Diffuse: * Unlimited undo * Easy keyboard navigation -## Requirements - -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 +## Installation 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). - -## 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. +For a more detailed documentation for users, translators and developers, see +the [documentation](docs/). ## Licenses diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b484bec --- /dev/null +++ b/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) diff --git a/docs/developers.md b/docs/developers.md new file mode 100644 index 0000000..0820e74 --- /dev/null +++ b/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). diff --git a/po/README.md b/docs/translators.md similarity index 75% rename from po/README.md rename to docs/translators.md index 2510820..e9008cb 100644 --- a/po/README.md +++ b/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,16 +74,19 @@ 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 -manual by copying the English version of the [DocBook manual][docbook-manual] -and then edit the contents. +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. + +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 -localized using search and replace. Manually add new search and replace rules +POSIX platforms. The conversion tools insert some English text that gets +localized using search and replace. Manually add new search and replace rules to these files: ../windows-installer/translations.txt diff --git a/docs/users.md b/docs/users.md new file mode 100644 index 0000000..7fd9905 --- /dev/null +++ b/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