mirror of
https://github.com/niess/python-appimage.git
synced 2026-03-13 20:00:19 +01:00
Use mkdocs-macros
This commit is contained in:
Valentin Niess
9
.readthedocs.yaml
Normal file
9
.readthedocs.yaml
Normal file
@@ -0,0 +1,9 @@
|
||||
version: 2
|
||||
|
||||
mkdocs:
|
||||
configuration: docs/mkdocs.yml
|
||||
|
||||
python:
|
||||
version: 3.8
|
||||
install:
|
||||
- requirements: docs/requirements.txt
|
||||
@@ -1,37 +1,35 @@
|
||||
<!-- This document describes the usage of the python-appimage utility
|
||||
{# This document describes the usage of the python-appimage utility.
|
||||
|
||||
The intended audience is developers. In addition, this document also provides
|
||||
some tips for packaging Python based applications.
|
||||
-->
|
||||
The intended audience is developers. In addition, this document also provides
|
||||
some tips for packaging Python based applications.
|
||||
#}
|
||||
|
||||
<script src="../js/highlight.min.js" defer></script>
|
||||
<script src="../js/apps.js" defer></script>
|
||||
{{ importjs("highlight.min") }}
|
||||
{{ importjs("apps") }}
|
||||
|
||||
{% include "references.md" %}
|
||||
|
||||
|
||||
# Developers corner
|
||||
|
||||
Python [AppImages][APPIMAGE] are built with the `python-appimage`{.inline}
|
||||
utility, available from [PyPI][PYPI]. This utility can also help packaging
|
||||
Python based applications as AppImages, using an existing Python AppImage and a
|
||||
recipe folder.
|
||||
{.justify}
|
||||
Python [AppImages][APPIMAGE] are built with the `python-appimage` utility,
|
||||
available from [PyPI][PYPI]. This utility can also help packaging Python based
|
||||
applications as AppImages, using an existing Python AppImage and a recipe
|
||||
folder.
|
||||
|
||||
!!! Caution
|
||||
The `python-appimage`{.inline} utility can only package applications that
|
||||
can be directly installed with `pip`{.inline}. For more advanced usage, one
|
||||
needs to extract the Python AppImage and to edit it, e.g. as explained in
|
||||
the [Advanced installation](index.md#advanced-installation) section.
|
||||
Additional details on this use case are provided
|
||||
[below](#advanced-packaging).
|
||||
{.justify}
|
||||
The `python-appimage` utility can only package applications that can be
|
||||
directly installed with `pip`. For more advanced usage, one needs to extract
|
||||
the Python AppImage and to edit it, e.g. as explained in the [Advanced
|
||||
installation](index.md#advanced-installation) section. Additional details
|
||||
on this use case are provided [below](#advanced-packaging).
|
||||
|
||||
|
||||
## Building a Python AppImage
|
||||
|
||||
The primary scope of `python-appimage`{.inline} is to relocate an existing
|
||||
Python installation inside an AppDir, and to build the corresponding AppImage.
|
||||
For example, the following
|
||||
{.justify}
|
||||
The primary scope of `python-appimage` is to relocate an existing Python
|
||||
installation inside an AppDir, and to build the corresponding AppImage. For
|
||||
example, the following
|
||||
|
||||
```bash
|
||||
python-appimage build local -p $(which python2)
|
||||
@@ -41,74 +39,62 @@ should build an AppImage of your local Python 2 installation, provided that it
|
||||
exists.
|
||||
|
||||
!!! Tip
|
||||
Help on available arguments and options to `python-appimage`{.inline} can be
|
||||
obtained with the `-h`{.inline .language-bash} flag. For example,
|
||||
`python-appimage build local -h`{.inline .language-none} provides help on
|
||||
local builds.
|
||||
{.justify}
|
||||
Help on available arguments and options to `python-appimage` can be obtained
|
||||
with the `-h` flag. For example, `python-appimage build local -h` provides
|
||||
help on local builds.
|
||||
|
||||
|
||||
<div markdown="1" class="capsule">
|
||||
{{ begin(".capsule") }}
|
||||
### Auxiliary tools
|
||||
|
||||
The `python-appimage`{.inline} utility relies on auxiliary tools that are
|
||||
downloaded and installed at runtime, on need. Those are
|
||||
[appimagetool][APPIMAGETOOL] for building AppImages, and [patchelf][PATCHELF] in
|
||||
order to edit ELFs runtime paths (`RPATH`{.inline}). Auxiliary tools are
|
||||
installed to the the user space. One can get their location with the
|
||||
`which`{.inline .language-none} command word. For example,
|
||||
{.justify}
|
||||
The `python-appimage` utility relies on auxiliary tools that are downloaded and
|
||||
installed at runtime, on need. Those are [appimagetool][APPIMAGETOOL] for
|
||||
building AppImages, and [patchelf][PATCHELF] in order to edit ELFs runtime paths
|
||||
(`RPATH`). Auxiliary tools are installed to the the user space. One can get
|
||||
their location with the `which` command word. For example,
|
||||
|
||||
```bash
|
||||
python-appimage which appimagetool
|
||||
```
|
||||
|
||||
returns the location of `appimagetool`{.inline}, if it has been installed. If
|
||||
not, the `install`{.inline} command word can be used in order to trigger its
|
||||
installation.
|
||||
{.justify}
|
||||
</div>
|
||||
returns the location of `appimagetool`, if it has been installed. If not, the
|
||||
`install` command word can be used in order to trigger its installation.
|
||||
{{ end(".capsule") }}
|
||||
|
||||
|
||||
## Manylinux Python AppImage
|
||||
|
||||
AppImages of your local `python`{.inline} are unlikely to be portable, except if
|
||||
you run an ancient Linux distribution. Indeed, a core component preventing
|
||||
portability across Linuses is the use of different versions of the
|
||||
`glibc`{.inline} system library. Hopefully, `glibc`{.inline} is highly backward
|
||||
compatible. Therefore, a simple work-around is to compile binaries using the
|
||||
oldest Linux distro you can afford to. This is the strategy used for creating
|
||||
portable AppImages, as well as for distributing Python site packages as
|
||||
ready-to-use binary [wheels][WHEELS].
|
||||
{.justify}
|
||||
AppImages of your local `python` are unlikely to be portable, except if you run
|
||||
an ancient Linux distribution. Indeed, a core component preventing portability
|
||||
across Linuses is the use of different versions of the `glibc` system library.
|
||||
Hopefully, `glibc` is highly backward compatible. Therefore, a simple
|
||||
work-around is to compile binaries using the oldest Linux distro you can afford
|
||||
to. This is the strategy used for creating portable AppImages, as well as for
|
||||
distributing Python site packages as ready-to-use binary [wheels][WHEELS].
|
||||
|
||||
The Python Packaging Authority (PyPA) has defined standard platform tags for
|
||||
building Python site packages, labelled [manylinux][MANYLINUX]. These build
|
||||
platforms are available as Docker images with various versions of Python already
|
||||
installed. The `python-appimage`{.inline} utility can be used to package those
|
||||
installs as AppImages. For example, the following command
|
||||
{.justify}
|
||||
installed. The `python-appimage` utility can be used to package those installs
|
||||
as AppImages. For example, the following command
|
||||
|
||||
```bash
|
||||
python-appimage build manylinux 2014_x86_64 cp310-cp310
|
||||
```
|
||||
|
||||
should build an AppImage of Python 3.10 using the CPython (_cp310-cp310_)
|
||||
install found in the `manylinux2014_x86_64`{.inline} Docker image.
|
||||
{.justify}
|
||||
install found in the `manylinux2014_x86_64` Docker image.
|
||||
|
||||
!!! Note
|
||||
Docker needs to be already installed on your system in order to build
|
||||
Manylinux Python images. However, the command above can be run on the host.
|
||||
That is, you need **not** to explictly shell inside the manylinux Docker
|
||||
image.
|
||||
{.justify}
|
||||
|
||||
!!! Tip
|
||||
A compilation of ready-to-use Manylinux Python AppImages is available from
|
||||
the [releases][RELEASES] area of the `python-appimage`{.inline} [GitHub
|
||||
the [releases][RELEASES] area of the `python-appimage` [GitHub
|
||||
repository][GITHUB]. These AppImages are updated weekly, on every Sunday.
|
||||
{.justify}
|
||||
|
||||
|
||||
## Simple packaging
|
||||
@@ -116,26 +102,12 @@ install found in the `manylinux2014_x86_64`{.inline} Docker image.
|
||||
The recipe folder contains
|
||||
the app metadata, a Python requirements file and an entry point script. Examples
|
||||
of recipes can be found on GitHub in the [applications][APPLICATIONS] folder.
|
||||
{.justify}
|
||||
|
||||
|
||||
## Advanced packaging
|
||||
|
||||
Alternatively, you can also manualy extract one of the Python
|
||||
[AppImages][APPIMAGE] as explained above and directly modify the content, e.g.
|
||||
`pip install`{.inline} your custom packages. Then, simply rebuild the AppImage
|
||||
using your favourite tool, e.g. [appimagetool][APPIMAGETOOL],
|
||||
[linuxdeploy][LINUXDEPLOY] or `python-appimage`{.inline}.
|
||||
{.justify}
|
||||
|
||||
|
||||
[APPIMAGE]: https://appimage.org
|
||||
[APPIMAGETOOL]: https://appimage.github.io/appimagetool
|
||||
[APPLICATIONS]: https://github.com/niess/python-appimage/tree/master/applications
|
||||
[GITHUB]: https://github.com/niess/python-appimage
|
||||
[LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy
|
||||
[MANYLINUX]: https://github.com/pypa/manylinux
|
||||
[PATCHELF]: https://github.com/NixOS/patchelf
|
||||
[PYPI]: https://pypi.org/project/python-appimage
|
||||
[RELEASES]: https://github.com/niess/python-appimage/releases
|
||||
[WHEELS]: https://pythonwheels.com/
|
||||
`pip install` your custom packages. Then, simply rebuild the AppImage using your
|
||||
favourite tool, e.g. [appimagetool][APPIMAGETOOL], [linuxdeploy][LINUXDEPLOY]
|
||||
or `python-appimage`.
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
/* Text justification */
|
||||
.justify {
|
||||
.justify, p {
|
||||
text-align: justify;
|
||||
text-justify: inter-word;
|
||||
}
|
||||
|
||||
|
||||
/* Patch for code highlighting */
|
||||
code.inline {
|
||||
background: transparent !important;
|
||||
.rst-content code,
|
||||
.rst-content .admonition code,
|
||||
.inline code {
|
||||
background: transparent;
|
||||
color: black;
|
||||
display: inline;
|
||||
overflow-wrap: break-word;
|
||||
|
||||
@@ -1,13 +1,15 @@
|
||||
<!-- This document describes the usage of Python AppImages, as runtimes.
|
||||
{# This document describes the usage of Python AppImages, as runtimes.
|
||||
|
||||
Note that some parts of this document are generated dynamically according to the
|
||||
reader's system configuration, and depending on released AppImages. The intent
|
||||
is to provide relevant examples to the reader, as well as a dynamic summary of
|
||||
available Python AppImages.
|
||||
-->
|
||||
Note that some parts of this document are generated dynamically according to
|
||||
the reader's system configuration, and depending on released AppImages. The
|
||||
intent is to provide relevant examples to the reader, as well as a dynamic
|
||||
summary of available Python AppImages.
|
||||
#}
|
||||
|
||||
<script src="js/highlight.min.js" defer></script>
|
||||
<script src="js/index.js" defer></script>
|
||||
{{ importjs("highlight.min") }}
|
||||
{{ importjs("index") }}
|
||||
|
||||
{% include "references.md" %}
|
||||
|
||||
|
||||
# Python AppImages
|
||||
@@ -15,110 +17,103 @@ available Python AppImages.
|
||||
We provide relocatable Python runtimes for _Linux_ systems, as
|
||||
[AppImages][APPIMAGE]. These runtimes have been extracted from
|
||||
[manylinux][MANYLINUX] Docker images.
|
||||
{.justify .append-releases-list}
|
||||
{{ "" | id("append-releases-list") }}
|
||||
|
||||
## Basic installation
|
||||
|
||||
Installing Python from an [AppImage][APPIMAGE] is as simple as downloading a
|
||||
single file and changing its mode to executable. For example, as
|
||||
{.justify}
|
||||
|
||||
``` { .bash #basic-installation-example }
|
||||
{{ begin("#basic-installation-example") }}
|
||||
```bash
|
||||
wget https://github.com/niess/python-appimage/releases/download\
|
||||
/python3.10/python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
|
||||
|
||||
chmod +x python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
|
||||
```
|
||||
{{ end("#basic-installation-example") }}
|
||||
|
||||
!!! Note
|
||||
As can be seen from the previous [example](#basic-installation-example), the
|
||||
AppImage name contains several informations. That are, the Python full
|
||||
version (*3.10.2*{#example-full-version}), the CPython tag
|
||||
(*cp310-cp310*{#example-python-tag}), the Linux compatibility tag
|
||||
(*manylinux2014*{#example-linux-tag}) and the machine architecture
|
||||
(*x86_64*{#example-arch-tag}).
|
||||
{.justify}
|
||||
version ({{ "3.10.2" | id("example-full-version") }}), the CPython tag
|
||||
({{ "cp310-cp310" | id("example-python-tag") }}), the Linux compatibility
|
||||
tag ({{ "manylinux2014" | id("example-linux-tag") }}) and the machine
|
||||
architecture ({{ "x86_64" | id("example-arch-tag") }}).
|
||||
|
||||
!!! Caution
|
||||
One needs to **select an AppImage** that matches **system requirements**. A
|
||||
summmary of available Python AppImages is provided at the
|
||||
[bottom](#available-python-appimages) of this page.
|
||||
{.justify}
|
||||
|
||||
|
||||
<div markdown="1" class="capsule">
|
||||
{{ begin(".capsule") }}
|
||||
### Creating a symbolic link
|
||||
|
||||
Since AppImages native names are rather lengthy, one might create a symbolic
|
||||
link, e.g. as
|
||||
{.justify}
|
||||
|
||||
``` { .bash #basic-installation-example-symlink }
|
||||
{{ begin("#basic-installation-example-symlink") }}
|
||||
```bash
|
||||
ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage python3.10
|
||||
```
|
||||
{{ end("#basic-installation-example-symlink") }}
|
||||
|
||||
Then, executing the AppImage as
|
||||
`./python3.10`{#basic-installation-example-execution .inline} should start a
|
||||
Python interactive session on _almost_ any Linux, provided that **fuse** is
|
||||
supported.
|
||||
{.justify}
|
||||
</div>
|
||||
|
||||
{{ "`./python3.10`" | id("basic-installation-example-execution") }} should
|
||||
start a Python interactive session on _almost_ any Linux, provided that **fuse**
|
||||
is supported.
|
||||
{{ end(".capsule") }}
|
||||
|
||||
!!! Tip
|
||||
Fuse is not supported on Windows Subsytem for Linux v1 (WSL1), preventing
|
||||
AppImages direct execution. Yet, one can still extract the content of Python
|
||||
AppImages and use them, as explained in the [Advanced
|
||||
installation](#advanced-installation) section.
|
||||
{.justify}
|
||||
|
||||
|
||||
## Installing site packages
|
||||
|
||||
Site packages can be installed using `pip`{.inline}, distributed with the
|
||||
AppImage. For example, the following
|
||||
{.justify}
|
||||
Site packages can be installed using `pip`, distributed with the AppImage. For
|
||||
example, the following
|
||||
|
||||
``` {.bash #site-packages-example}
|
||||
{{ begin("#site-packages-example") }}
|
||||
```bash
|
||||
./python3.10 -m pip install numpy
|
||||
```
|
||||
{{ end("#site-packages-example") }}
|
||||
|
||||
installs the numpy package, where it is assumed that a symlink to the AppImage
|
||||
has been previously created. When using the **basic installation** scheme, by
|
||||
default Python packages are installed to your **user space**, i.e. under
|
||||
`~/.local`{.inline} on Linux.
|
||||
{.justify}
|
||||
`~/.local` on Linux.
|
||||
|
||||
!!! Note
|
||||
AppImage are read-only. Therefore, site packages cannot be directly
|
||||
installed to the AppImage. However, the AppImage can be extracted, as
|
||||
explained in the [Advanced installation](#advanced-installation) section.
|
||||
{.justify}
|
||||
|
||||
|
||||
<div markdown="1" class="capsule">
|
||||
{{ begin(".capsule") }}
|
||||
### Alternative site packages location
|
||||
|
||||
One can
|
||||
specify an alternative installation directory for site packages using the
|
||||
`--target`{.inline .language-bash} option of pip. For example, the following
|
||||
{.justify}
|
||||
`--target` option of pip. For example, the following
|
||||
|
||||
``` {.bash #site-packages-example-target}
|
||||
{{ begin("#site-packages-example-target") }}
|
||||
```bash
|
||||
./python3.10 -m pip install --target=$(pwd)/packages numpy
|
||||
```
|
||||
{{ end("#site-packages-example-target") }}
|
||||
|
||||
installs the numpy package besides the AppImage, in a `packages`{.inline}
|
||||
folder.
|
||||
{.justify}
|
||||
</div>
|
||||
installs the numpy package besides the AppImage, in a `packages` folder.
|
||||
{{ end(".capsule") }}
|
||||
|
||||
!!! Tip
|
||||
Packages installed in non standard locations are not automatically
|
||||
found by Python. Their location must be aded to
|
||||
`sys.path`{.inline .language-python}, e.g. using the
|
||||
`PYTHONPATH`{.inline .language-bash} environment variable.
|
||||
{.justify}
|
||||
Packages installed in non standard locations are not automatically found by
|
||||
Python. Their location must be aded to `sys.path`, e.g. using the
|
||||
`PYTHONPATH` environment variable.
|
||||
|
||||
!!! Caution
|
||||
While Python AppImages are relocatable, site packages might not be. In
|
||||
@@ -126,40 +121,34 @@ folder.
|
||||
location of the Python runtime. If the Python AppImage is moved, then these
|
||||
scripts will fail. This can be patched by editing the script
|
||||
[shebang][SHEBANG], or be reinstalling the corresponding package.
|
||||
{.justify}
|
||||
|
||||
|
||||
## Isolating from the user space
|
||||
|
||||
Python AppImages are not isolated from the user space. Therefore, by default
|
||||
site packages located under `~/.local`{.inline} are loaded instead of system
|
||||
ones. Note that this is the usual Python runtime behaviour. However, it can be
|
||||
conflictual in some cases.
|
||||
{.justify}
|
||||
site packages located under `~/.local` are loaded instead of system ones. Note
|
||||
that this is the usual Python runtime behaviour. However, it can be conflictual
|
||||
in some cases.
|
||||
|
||||
In order to disable user site packages, one can use the
|
||||
`-s`{.inline .language-bash} option of the Python runtime. For example,
|
||||
invoking the Python AppImage as
|
||||
`./python3.10 -s`{.inline .language-bash #user-isolation-example} prevents user
|
||||
packages to be loaded.
|
||||
{.justify}
|
||||
In order to disable user site packages, one can use the `-s` option of the
|
||||
Python runtime. For example, invoking the Python AppImage as {{ "`./python3.10
|
||||
-s`" | id("user-isolation-example") }} prevents user packages to be loaded.
|
||||
|
||||
|
||||
## Using a virtual environement
|
||||
|
||||
Isolation can also be achieved with a [virtual environment][VENV]. Python
|
||||
AppImages can create a `venv`{.inline} using the standard syntax, e.g. as
|
||||
{.justify}
|
||||
AppImages can create a `venv` using the standard syntax, e.g. as
|
||||
|
||||
``` {.bash #venv-example}
|
||||
{{ begin("#venv-example") }}
|
||||
```bash
|
||||
./python3.10 -m venv /path/to/new/virtual/environment
|
||||
```
|
||||
{{ end("#venv-example") }}
|
||||
|
||||
However, the virtual environment fails setting up `pip`{.inline}, despite the
|
||||
latter is packaged with the AppImage. Yet, this can be patched by calling
|
||||
`ensurepip`{.inline} from within the `venv`{.inline}, after its creation. For
|
||||
example, as
|
||||
{.justify}
|
||||
However, the virtual environment fails setting up `pip`, despite the latter is
|
||||
packaged with the AppImage. Yet, this can be patched by calling `ensurepip` from
|
||||
within the `venv`, after its creation. For example, as
|
||||
|
||||
```bash
|
||||
source /path/to/new/virtual/environment/bin/activate
|
||||
@@ -173,48 +162,47 @@ python -m ensurepip
|
||||
The [basic installation](#basic-installation) scheme described previously has
|
||||
some limitations when using Python AppImages as a runtime. For example, site
|
||||
packages need to be installed to a separate location. This can be solved by
|
||||
extracting a Python AppImage to an `*.AppDir`{.inline} directory, e.g. as
|
||||
{.justify}
|
||||
extracting a Python AppImage to an `*.AppDir` directory, e.g. as
|
||||
|
||||
``` {.bash #advanced-installation-example}
|
||||
|
||||
{{ begin("#advanced-installation-example") }}
|
||||
```bash
|
||||
./python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage --appimage-extract
|
||||
|
||||
mv squashfs-root python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir
|
||||
|
||||
ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir/AppRun python3.10
|
||||
```
|
||||
{{ end("#advanced-installation-example") }}
|
||||
|
||||
Then, by default **site packages** are installed to the extracted **AppDir**,
|
||||
when using `pip`{.inline}. In addition, executable scripts installed by
|
||||
`pip`{.inline} are patched in order to use relative [shebangs][SHEBANG].
|
||||
Consequently, the AppDir can be freely moved around.
|
||||
{.justify}
|
||||
when using `pip`. In addition, executable scripts installed by `pip` are patched
|
||||
in order to use relative [shebangs][SHEBANG]. Consequently, the AppDir can be
|
||||
freely moved around.
|
||||
|
||||
!!! Note
|
||||
Python AppDirs follow the [manylinux][MANYLINUX] installation scheme.
|
||||
Executable scripts are installed under `AppDir/opt/pythonX.Y/bin`{.inline}
|
||||
where _X_ and _Y_ in _pythonX.Y_ stand for the major and minor version
|
||||
numbers. Site packages are located under
|
||||
`AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`{.inline}.
|
||||
{.justify}
|
||||
Executable scripts are installed under `AppDir/opt/pythonX.Y/bin` where _X_
|
||||
and _Y_ in _pythonX.Y_ stand for the major and minor version numbers. Site
|
||||
packages are located under
|
||||
`AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`.
|
||||
|
||||
!!! Tip
|
||||
As for Python AppImages, by default the extracted runtime is [not isolated
|
||||
from the user space](#isolating-from-the-user-space). This behaviour can be
|
||||
changed by editing the `AppDir/AppRun`{.inline} wrapper script, and by
|
||||
adding the `-s`{.inline .language-bash} option at the very bottom, where
|
||||
Python is invoked.
|
||||
{.justify}
|
||||
changed by editing the `AppDir/AppRun` wrapper script, and by adding the
|
||||
`-s` option at the very bottom, where Python is invoked.
|
||||
|
||||
|
||||
<div markdown="1" class="capsule">
|
||||
{{ begin(".capsule") }}
|
||||
### Repackaging the AppImage
|
||||
|
||||
An extracted AppDir can be re-packaged as an AppImage using
|
||||
[appimagetool][APPIMAGETOOL], e.g. as
|
||||
{.justify}
|
||||
|
||||
``` {.bash #repackaging-example}
|
||||
|
||||
{{ begin("#repackaging-example") }}
|
||||
```bash
|
||||
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/\
|
||||
appimagetool-x86_64.AppImage
|
||||
|
||||
@@ -224,17 +212,16 @@ chmod +x appimagetool-x86_64.AppImage
|
||||
python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir \
|
||||
python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
|
||||
```
|
||||
{{ end("#repackaging-example") }}
|
||||
|
||||
This allows to customize your Python AppImage, for example by adding your
|
||||
preferred site packages.
|
||||
{.justify}
|
||||
</div>
|
||||
{{ end(".capsule") }}
|
||||
|
||||
!!! Note
|
||||
Python AppImages can also be used for packaging Python based applications,
|
||||
as AppImages. Additional details are provided in the [developers
|
||||
section](apps).
|
||||
{.justify}
|
||||
|
||||
|
||||
## Available Python AppImages
|
||||
@@ -243,22 +230,13 @@ A summary of available Python AppImages [releases][RELEASES] is provided in the
|
||||
[table](#appimages-download-links) below. Clicking on a badge should download
|
||||
the corresponding AppImage.
|
||||
|
||||
{{ begin("#suggest-appimage-download") }}
|
||||
!!! Caution
|
||||
According to your browser, your system would not be compatible with Python
|
||||
Appimages.
|
||||
{.justify #suggest-appimage-download}
|
||||
According to your browser, your system would not be compatible with
|
||||
Python Appimages.
|
||||
{{ end("#suggest-appimage-download") }}
|
||||
|
||||
<div id="appimages-download-links">
|
||||
<p style="color: red; text-align: center">
|
||||
<could not download release data from
|
||||
https://github.com/niess/python-appimage/releases>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
||||
[APPIMAGE]: https://appimage.org
|
||||
[APPIMAGETOOL]: https://appimage.github.io/appimagetool
|
||||
[MANYLINUX]: https://github.com/pypa/manylinux
|
||||
[RELEASES]: https://github.com/niess/python-appimage/releases
|
||||
[SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)
|
||||
[VENV]: https://docs.python.org/3/library/venv.html
|
||||
{{ begin("#appimages-download-links") }}
|
||||
!!! Danger
|
||||
Could not download releases metadata from {{ github_api.releases | url }}.
|
||||
{{ end("#appimages-download-links") }}
|
||||
|
||||
@@ -1,5 +1,2 @@
|
||||
/* Perform the syntaxic highlighting */
|
||||
hljs.configure({
|
||||
cssSelector: "code"
|
||||
});
|
||||
hljs.highlightAll();
|
||||
|
||||
@@ -61,7 +61,7 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
|
||||
for (const release of releases) {
|
||||
elements.push(`<a href="${release.url}">${release.version}</a>`)
|
||||
}
|
||||
$(".append-releases-list").append(
|
||||
$("#append-releases-list").append(
|
||||
" Available Python versions are " +
|
||||
elements.slice(0, -1).join(", ") +
|
||||
" and " +
|
||||
@@ -86,9 +86,14 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
|
||||
/* Strip blocks of whitespaces, e.g. at line start */
|
||||
function stripws (s) { return s.replace(/ +/g, ""); }
|
||||
|
||||
/* Utility function for setting an inline code */
|
||||
function set_inline (selector, code) {
|
||||
$(selector).children().html(stripws(code));
|
||||
}
|
||||
|
||||
/* Utility function for setting a code snippet */
|
||||
function set_snippet (selector, code) {
|
||||
$(selector).children().html(stripws(code));
|
||||
$(selector).children().children().html(stripws(code));
|
||||
}
|
||||
|
||||
/* Generate the examples */
|
||||
@@ -128,7 +133,7 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
|
||||
ln -s ${asset.name} python${release.version}
|
||||
`);
|
||||
|
||||
$("#basic-installation-example-execution").html(
|
||||
set_inline("#basic-installation-example-execution",
|
||||
`./python${release.version}`
|
||||
);
|
||||
|
||||
@@ -140,8 +145,9 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
|
||||
./python${release.version} -m pip install --target=$(pwd)/packages numpy
|
||||
`);
|
||||
|
||||
$("#user-isolation-example").html(
|
||||
`./python${release.version} -s`);
|
||||
set_inline("#user-isolation-example",
|
||||
`./python${release.version} -s`
|
||||
);
|
||||
|
||||
set_snippet("#venv-example", `\
|
||||
./python${release.version} -m venv /path/to/new/virtual/environment
|
||||
@@ -234,27 +240,24 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
|
||||
html.push("<caption>Summary of available Python AppImages.</caption>");
|
||||
html.push("</table>");
|
||||
|
||||
$("#appimages-download-links").html(html.join("\n"));
|
||||
const element = $("#appimages-download-links");
|
||||
element.html(html.join("\n"));
|
||||
}
|
||||
|
||||
/* Suggest an AppImage */
|
||||
if (host_arch != undefined) {
|
||||
const body = $("#suggest-appimage-download");
|
||||
body.html(stripws(`\
|
||||
const main = $("#suggest-appimage-download").children().first();
|
||||
main.attr("class", "admonition tip");
|
||||
const children = main.children();
|
||||
children.first().text("Tip");
|
||||
children.eq(1).html(stripws(`\
|
||||
According to your browser, your system is an ${host_arch} Linux.
|
||||
Therefore, we recommend that you download an ${host_arch} AppImage
|
||||
with Manylinux ${suggested_appimage.linux} compatibility. For
|
||||
example, ${badge(suggested_appimage, false)}.
|
||||
`));
|
||||
|
||||
const parents = body.parent();
|
||||
parents.attr("class", "admonition tip");
|
||||
parents.children().first().text("Tip");
|
||||
}
|
||||
|
||||
/* Perform the syntaxic highlighting */
|
||||
hljs.configure({
|
||||
cssSelector: "code"
|
||||
});
|
||||
hljs.highlightAll();
|
||||
});
|
||||
|
||||
14
docs/include/references.md
Normal file
14
docs/include/references.md
Normal file
@@ -0,0 +1,14 @@
|
||||
{# References used in the documentation #}
|
||||
|
||||
[APPIMAGE]: https://appimage.org/
|
||||
[APPIMAGETOOL]: https://appimage.github.io/appimagetool/
|
||||
[APPLICATIONS]: {{ config.repo_url }}tree/master/applications/
|
||||
[GITHUB]: {{ config.repo_url }}
|
||||
[LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy/
|
||||
[MANYLINUX]: https://github.com/pypa/manylinux/
|
||||
[PATCHELF]: https://github.com/NixOS/patchelf/
|
||||
[PYPI]: https://pypi.org/project/python-appimaAge/
|
||||
[RELEASES]: {{ config.repo_url }}releases/
|
||||
[SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)/
|
||||
[VENV]: https://docs.python.org/3/library/venv.html/
|
||||
[WHEELS]: https://pythonwheels.com/
|
||||
93
docs/main.py
Normal file
93
docs/main.py
Normal file
@@ -0,0 +1,93 @@
|
||||
import os
|
||||
|
||||
def define_env(env):
|
||||
"""Custom filters and macros"""
|
||||
|
||||
def format_attributes(*args, **kwargs):
|
||||
"""Format HTML attributes"""
|
||||
if args:
|
||||
cls, id_ = [], None
|
||||
for arg in args:
|
||||
if arg[0] == ".":
|
||||
cls.append(arg[1:])
|
||||
elif arg[0] == "#":
|
||||
id_ = arg[1:]
|
||||
else:
|
||||
raise ValueError(f"Invalid attribute ({arg})")
|
||||
|
||||
if cls:
|
||||
try:
|
||||
kwargs["class"] += " " + " ".join(cls)
|
||||
except KeyError:
|
||||
kwargs["class"] = " ".join(cls)
|
||||
|
||||
if id_:
|
||||
kwargs["id"] = id_
|
||||
|
||||
if kwargs:
|
||||
attr = []
|
||||
for k, v in kwargs.items():
|
||||
attr.append(f"{k} = \"{v}\"")
|
||||
attr = " ".join(attr)
|
||||
else:
|
||||
attr = ""
|
||||
|
||||
return attr
|
||||
|
||||
|
||||
@env.filter
|
||||
def attr(text, *args, **kwargs):
|
||||
"""Add HTML attributes to a text using a <span>"""
|
||||
|
||||
attr = format_attributes(*args, **kwargs)
|
||||
|
||||
return f"<span {attr} markdown=\"1\">{text}</span>"
|
||||
|
||||
|
||||
@env.filter
|
||||
def cls(text, *args):
|
||||
"""Add HTML class(es) to a text using a <span>"""
|
||||
|
||||
cls = " ".join(args)
|
||||
|
||||
return f"<span class=\"{cls}\" marckdown=\"1\">{text}</span>"
|
||||
|
||||
|
||||
@env.filter
|
||||
def id(text, id_):
|
||||
"""Add HTML id to a text using a <span>"""
|
||||
|
||||
return f"<span id=\"{id_}\" markdown=\"1\">{text}</span>"
|
||||
|
||||
|
||||
@env.filter
|
||||
def url(raw):
|
||||
"""Wrap a raw URL with a link"""
|
||||
|
||||
return f"[{raw}]({raw})"
|
||||
|
||||
|
||||
@env.macro
|
||||
def begin(*args, **kwargs):
|
||||
"""Start a new HTML <div>"""
|
||||
|
||||
attr = format_attributes(*args, **kwargs)
|
||||
|
||||
return f"<div {attr} markdown=\"1\">"
|
||||
|
||||
|
||||
@env.macro
|
||||
def end(comment=None):
|
||||
"""End an HTML <div>"""
|
||||
|
||||
return "</div>"
|
||||
|
||||
|
||||
@env.macro
|
||||
def importjs(name):
|
||||
"""Import a JavaScript script"""
|
||||
|
||||
current = "/" + env.page.url
|
||||
relpath = os.path.relpath("/js", start=current)
|
||||
|
||||
return f"<script src=\"{relpath}/{name}.js\" defer></script>"
|
||||
@@ -3,8 +3,8 @@ site_description: AppImage distributions of Python
|
||||
site_author: Valentin Niess
|
||||
copyright: GPL-3.0
|
||||
|
||||
repo_url: https://github.com/niess/python-appimage
|
||||
edit_uri: edit/master/docs/docs
|
||||
repo_url: https://github.com/niess/python-appimage/
|
||||
edit_uri: edit/master/docs/
|
||||
|
||||
nav:
|
||||
- Python AppImages: index.md
|
||||
@@ -15,9 +15,19 @@ theme:
|
||||
navigation_depth: 3
|
||||
highlightjs: no
|
||||
|
||||
plugins:
|
||||
- macros:
|
||||
include_dir: docs/include
|
||||
- search
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- attr_list
|
||||
- md_in_html
|
||||
|
||||
extra_css: [css/extra.css, css/nord.min.css]
|
||||
|
||||
extra_javascript: [js/apps.js, js/highlight.min.js, js/index.js]
|
||||
|
||||
extra:
|
||||
github_api:
|
||||
releases: https://api.github.com/repos/niess/python-appimage/releases
|
||||
|
||||
@@ -1 +1,2 @@
|
||||
mkdocs==1.2.3
|
||||
mkdocs-macros-plugin==0.6.4
|
||||
|
||||
Reference in New Issue
Block a user