Improve the documentation
* Simplify the main README.md * Moved more detailed documentations into a new docs/ directory
This commit is contained in:
Romain Failliot
parent
3fcb76d22c
commit
d0fb098fe5
|
|
@ -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
|
||||
|
|
|
|||
105
README.md
105
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue