add docs to main branch
This commit is contained in:
Wes Barnett
parent
95dce2a22d
commit
1e6629aa08
10 changed files with 397 additions and 0 deletions
28
.github/workflows/docs.yml
vendored
Normal file
28
.github/workflows/docs.yml
vendored
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
name: Docs
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Install Python
|
||||
uses: actions/setup-python@v1
|
||||
with:
|
||||
python-version: 3.9
|
||||
- name: Install dependencies
|
||||
run: python -m pip install --upgrade pip sphinx
|
||||
- name: Build docs
|
||||
run: cd docs && sphinx-build source build
|
||||
- name: Deploy
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./docs/build
|
||||
publish_branch: gh-pages
|
||||
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
35
docs/make.bat
Normal file
35
docs/make.bat
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=source
|
||||
set BUILDDIR=build
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
52
docs/source/conf.py
Normal file
52
docs/source/conf.py
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'snap-pac'
|
||||
copyright = '2021, Wes Barnett, PhD'
|
||||
author = 'Wes Barnett, PhD'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = []
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
34
docs/source/configuration.rst
Normal file
34
docs/source/configuration.rst
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
Configuration
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Configuration is done via Python ini configuration files. The defaults
|
||||
should be suitable for most users, so you may not need to do any configuration at all.
|
||||
By default only the ``root`` snapper configuration is snapshotted.
|
||||
|
||||
A commented example configuration files is located at ``/etc/snap-pac.ini.example``.
|
||||
|
||||
To configure, copy the example configuration file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cp /etc/snap-pac.ini{.example,}
|
||||
|
||||
Then edit with your favorite editor. The file is commented and should be
|
||||
self-explanatory.
|
||||
|
||||
Each section corresponds with a snapper configuration. Add additional sections to add
|
||||
other snapper configurations to be snapshotted. By default, only the root configuration
|
||||
is snapshotted.
|
||||
|
||||
Environment Variables
|
||||
---------------------
|
||||
|
||||
To temporarily prevent snapshots from being performed for a single pacman
|
||||
command, set the environment variable ``SNAP_PAC_SKIP``. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo SNAP_PAC_SKIP=y pacman -Syu
|
||||
92
docs/source/examples.rst
Normal file
92
docs/source/examples.rst
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
Example
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Here is an example of how the snapshots are created and how to rollback and pacman
|
||||
transaction. Here the nano package is installed:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -S nano
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
resolving dependencies...
|
||||
looking for conflicting packages...
|
||||
|
||||
Packages (1) nano-2.5.3-1
|
||||
|
||||
Total Installed Size: 2.14 MiB
|
||||
|
||||
:: Proceed with installation? [Y/n] Y
|
||||
(1/1) checking keys in keyring [######################################] 100%
|
||||
(1/1) checking package integrity [######################################] 100%
|
||||
(1/1) loading package files [######################################] 100%
|
||||
(1/1) checking for file conflicts [######################################] 100%
|
||||
(1/1) checking available disk space [######################################] 100%
|
||||
:: Running pre-transaction hooks...
|
||||
(1/1) Performing snapper pre snapshots for the following configurations...
|
||||
=> root: 1033
|
||||
:: Processing package changes...
|
||||
(1/1) installing nano [######################################] 100%
|
||||
:: Running post-transaction hooks...
|
||||
(1/1) Performing snapper post snapshots for the following configurations...
|
||||
=> root: 1034
|
||||
|
||||
The snapper snapshot number is given for each snapper configuration that is used. This
|
||||
is also logged in pacman's log.
|
||||
|
||||
Here are the snapshots created before and after the pacman transaction:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
snapper -c root list -t pre-post | tail -n 1
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
1033 | 1034 | Fri 22 Apr 2016 01:54:13 PM CDT | Fri 22 Apr 2016 01:54:14 PM CDT | pacman -S nano |
|
||||
|
||||
Here is what changed during the transaction:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
snapper -c root status 1033..1034
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
+..... /etc/nanorc
|
||||
c..... /etc/snapper/.snap-pac-pre
|
||||
+..... /usr/bin/nano
|
||||
+..... /usr/bin/rnano
|
||||
+..... /usr/share/doc/nano
|
||||
+..... /usr/share/doc/nano/faq.html
|
||||
+..... /usr/share/doc/nano/fr
|
||||
+..... /usr/share/doc/nano/fr/nano.1.html
|
||||
+..... /usr/share/doc/nano/fr/nanorc.5.html
|
||||
+..... /usr/share/doc/nano/fr/rnano.1.html
|
||||
|
||||
The above output is truncated, but it continues. See the `snapper(8)
|
||||
<http://snapper.io/manpages/snapper.html>`_ to for what each symbol means. You can also
|
||||
do ``snapper diff`` in the same way.
|
||||
|
||||
Then, to undo the pacman transaction:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
snapper -c root undochange 1033..1034
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
create:0 modify:3 delete:100
|
||||
|
||||
Now nano is no longer installed, along with all the files it changed:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -Qi nano
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
error: package 'nano' was not found
|
||||
42
docs/source/faq.rst
Normal file
42
docs/source/faq.rst
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
FAQ
|
||||
===
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
**Does snap-pac backup non-btrfs /boot partitions?**
|
||||
|
||||
No, but you can add a hook that does it for you. It would be something like the following:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[Trigger]
|
||||
Operation = Upgrade
|
||||
Operation = Install
|
||||
Operation = Remove
|
||||
Type = Package
|
||||
Target = linux
|
||||
|
||||
[Action]
|
||||
Description = Backing up /boot...
|
||||
When = PreTransaction
|
||||
Exec = /usr/bin/rsync -avzq --delete /boot /.bootbackup
|
||||
|
||||
|
||||
**How do I link old kernel modules automatically when the kernel is upgraded?**
|
||||
|
||||
This behavior is no longer a part of this package. Use a pacman hook like the following:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[Trigger]
|
||||
Operation = Upgrade
|
||||
Operation = Install
|
||||
Operation = Remove
|
||||
Type = Package
|
||||
Target = linux
|
||||
|
||||
[Action]
|
||||
Description = Symlinking old kernel modules...
|
||||
When = PostTransaction
|
||||
Exec = /usr/bin/bash -c "find /usr/lib/modules -xtype l -delete; ln -sv /.snapshots/$(snapper -c root list | awk 'END{print $1}')/snapshot/usr/lib/modules/$(uname -r) /usr/lib/modules/"
|
||||
41
docs/source/index.rst
Normal file
41
docs/source/index.rst
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
.. snap-pac documentation master file, created by
|
||||
sphinx-quickstart on Thu Mar 11 19:49:12 2021.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to snap-pac's documentation!
|
||||
====================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
configuration
|
||||
examples
|
||||
troubleshooting
|
||||
faq
|
||||
|
||||
This is a set of `pacman <https://archlinux.org/pacman/>`_ hooks and script that causes
|
||||
`snapper <http://snapper.io/>`_ to automatically take a pre and post snapshot before and
|
||||
after pacman transactions, similar to how `YaST <https://yast.opensuse.org/>`_ does with
|
||||
OpenSuse. This provides a simple way to undo changes to a system after a pacman
|
||||
transaction.
|
||||
|
||||
Because these are pacman hooks, it doesn't matter how you call pacman—whether
|
||||
directly, through an AUR helper, or using an alias—snapper will create the snapshots
|
||||
when pacman installs, upgrades, or removes a package. The pacman command used is
|
||||
logged in the snapper description for the snapshots. Additionally the snapshot numbers
|
||||
are output to the screen and to the pacman log for each snapper configuration during the
|
||||
pacman transaction, so that the user can easily find which changes he or she may want to
|
||||
revert.
|
||||
|
||||
To undo changes from a pacman transaction, use ``snapper undochange``. See the `snapper
|
||||
documentation <http://snapper.io/documentation.html>`_ for more details as well as
|
||||
examples.
|
||||
|
||||
If you have severe breakage—like snapper is gone for some reason and you can't get it
|
||||
back—you'll have to resort to more extreme methods, such as taking a snapshot of the pre
|
||||
snapshot and making it the default subvolume or mounting it as /. Most likely you'll
|
||||
need to use a live USB to get into a chroot environment to do any of these things.
|
||||
Snapper has a ``snapper rollback`` feature, but your setup has to be properly configured to
|
||||
use it. The exact procedure depends on your specific setup. Be careful.
|
||||
30
docs/source/installation.rst
Normal file
30
docs/source/installation.rst
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
Installation
|
||||
============
|
||||
|
||||
Install the ``snap-pac`` package using pacman:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -S snap-pac
|
||||
|
||||
Alternatively download the `latest release and signature
|
||||
<https://github.com/wesbarnett/snap-pac/releases>`_. Then, verify the download:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
gpg --verify snap-pac-<version>.tar.gz.sig
|
||||
|
||||
where ``<version>`` is the version number you downloaded.
|
||||
|
||||
Finally, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make install
|
||||
|
||||
I have signed the release tarball and commits with my PGP key. Starting with release
|
||||
2.2, the tarballs are signed with my key with fingerprint
|
||||
``F7B28C61944FE30DABEEB0B01070BCC98C18BD66``.
|
||||
|
||||
For previous releases, the key's fingerprint was
|
||||
``8535CEF3F3C38EE69555BF67E4B5E45AA3B8C5C3``.
|
||||
23
docs/source/troubleshooting.rst
Normal file
23
docs/source/troubleshooting.rst
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
Troubleshooting
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
**snap-pac is only taking snapshots of the root configuration.**
|
||||
|
||||
That's the default behavior. See :doc:`configuration`.
|
||||
|
||||
**No snapshots are being taken when I run pacman.**
|
||||
|
||||
No snapper configurations are set up for snap-pac's pacman hooks. By default snap-pac
|
||||
will take snapshots for the root configuration and any other configuration which has
|
||||
SNAPSHOT set to yes in its configuration file. See :doc:`configuration`.
|
||||
|
||||
**After restoring snapshot from snap-pac, the pacman database is locked.**
|
||||
|
||||
The pre/post snaphots are taken while pacman is running, so this is expected. Follow
|
||||
the instructions pacman gives you (*e.g.*, removing the lock file). You can add the
|
||||
database lock file to a snapper filter so that snapper won't consider it when
|
||||
performing snapper diff, snapper status, snapper undochange, etc. See the Filters
|
||||
section in `snapper(8) <http://snapper.io/manpages/snapper.html>`_ for more information.
|
||||
Loading…
Add table
Reference in a new issue