improve wording in documentation

This commit is contained in:
Evgenii Alekseev 2022-12-02 15:45:01 +02:00
parent 7aa91f9e2e
commit 262462d3c3
51 changed files with 73 additions and 70 deletions

View File

@ -36,6 +36,6 @@ The application provides reasonable defaults which allow to use it out-of-box; h
## Live demos
* [Build status page](https://ahriman-demo.arcanis.me). You can login as `demo` user by using `demo` password. However, you will not be able to run tasks.
* [Build status page](https://ahriman-demo.arcanis.me). You can log in as `demo` user by using `demo` password. However, you will not be able to run tasks.
* [Repository index](http://repo.arcanis.me/x86_64/index.html).
* [Telegram feed](https://t.me/arcanisrepo).

View File

@ -1,4 +1,4 @@
.TH AHRIMAN "1" "2022\-11\-29" "ahriman" "Generated Python Manual"
.TH AHRIMAN "1" "2022\-12\-02" "ahriman" "Generated Python Manual"
.SH NAME
ahriman
.SH SYNOPSIS
@ -509,7 +509,7 @@ root path of the extracted files
usage: ahriman repo\-setup [\-h] [\-\-build\-as\-user BUILD_AS_USER] [\-\-build\-command BUILD_COMMAND]
[\-\-from\-configuration FROM_CONFIGURATION] [\-\-makeflags\-jobs | \-\-no\-makeflags\-jobs]
[\-\-multilib | \-\-no\-multilib] \-\-packager PACKAGER \-\-repository REPOSITORY [\-\-sign\-key SIGN_KEY]
[\-\-sign\-target {disabled,pacakges,repository}] [\-\-web\-port WEB_PORT]
[\-\-sign\-target {disabled,packages,repository}] [\-\-web\-port WEB_PORT]
[\-\-web\-unix\-socket WEB_UNIX_SOCKET]
create initial service configuration, requires root
@ -548,7 +548,7 @@ repository name
sign key id
.TP
\fB\-\-sign\-target\fR \fI\,{disabled,pacakges,repository}\/\fR
\fB\-\-sign\-target\fR \fI\,{disabled,packages,repository}\/\fR
sign options
.TP
@ -590,7 +590,7 @@ run triggers on empty build result as configured by settings
.TP
\fBtrigger\fR
instead of running all triggers as set by configuration, just process specified ones oin order of metion
instead of running all triggers as set by configuration, just process specified ones in order of mention
.SH COMMAND \fI\,'ahriman repo\-update'\/\fR
usage: ahriman repo\-update [\-h] [\-\-dry\-run] [\-e] [\-\-aur | \-\-no\-aur] [\-\-local | \-\-no\-local] [\-\-manual | \-\-no\-manual]

View File

@ -346,7 +346,7 @@ The default action (in case if no arguments provided) is ``repo-update``. Basica
docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
``--privileged`` flag is required to make mount possible inside container. In order to make data available outside of container, you would need to mount local (parent) direcotry inside container by using ``-v /path/to/local/repo:/var/lib/ahriman`` argument, where ``/path/to/local/repo`` is a path to repository on local machine. In addition, you can pass own configuration overrides by using the same ``-v`` flag, e.g.:
``--privileged`` flag is required to make mount possible inside container. In order to make data available outside of container, you would need to mount local (parent) directory inside container by using ``-v /path/to/local/repo:/var/lib/ahriman`` argument, where ``/path/to/local/repo`` is a path to repository on local machine. In addition, you can pass own configuration overrides by using the same ``-v`` flag, e.g.:
.. code-block:: shell

View File

@ -19,7 +19,7 @@ For the configuration details and settings explanation kindly refer to the :doc:
This trigger will be called before any action (``on_start``) and pulls remote PKGBUILD repository locally; after that it copies found PKGBUILDs from the cloned repository to the local cache. It is useful in case if you have patched PGKBUILDs (or even missing in AUR) which you would like to use for package building and, technically, just simplifies the local package building.
In order to update those packages you would need to clone your repository separately, make changes in PKGBUILD (e.g. bump version and update checksums), commit them and push back. On the next ahriman's repository update, it will pull changes you commited and will perform package update.
In order to update those packages you would need to clone your repository separately, make changes in PKGBUILD (e.g. bump version and update checksums), commit them and push back. On the next ahriman's repository update, it will pull changes you committed and will perform package update.
``ahriman.core.gitremote.RemotePushTrigger``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

View File

@ -29,12 +29,12 @@
await copyToClipboard(logs, packageInfoLogsCopyButton);
}
function showLogs(package) {
const isPackageBaseSet = package !== undefined;
function showLogs(packageBase) {
const isPackageBaseSet = packageBase !== undefined;
if (isPackageBaseSet)
packageInfoModal.data("package", package); // set package base as currently used
packageInfoModal.data("package", packageBase); // set package base as currently used
else
package = packageInfoModal.data("package"); // read package base from the current window attribute
packageBase = packageInfoModal.data("package"); // read package base from the current window attribute
const headerClass = status => {
if (status === "pending") return ["bg-warning"];
@ -45,7 +45,7 @@
};
$.ajax({
url: `/api/v1/packages/${package}/logs`,
url: `/api/v1/packages/${packageBase}/logs`,
type: "GET",
dataType: "json",
success: response => {
@ -60,7 +60,7 @@
},
error: (jqXHR, _, errorThrown) => {
// show failed modal in case if first time loading
if (isPackageBaseSet) showFailure("Load failure", `Could not load package ${package} logs:`, errorThrown);
if (isPackageBaseSet) showFailure("Load failure", `Could not load package ${packageBase} logs:`, errorThrown);
},
});
}

View File

@ -18,7 +18,7 @@
pre[class*="language-"] button{
position: absolute;
top: 0px;
top: 0;
right: 5px;
}
</style>

View File

@ -717,7 +717,7 @@ def _set_repo_triggers_parser(root: SubParserAction) -> argparse.ArgumentParser:
description="run triggers on empty build result as configured by settings",
formatter_class=_formatter)
parser.add_argument("trigger", help="instead of running all triggers as set by configuration, just process "
"specified ones oin order of metion", nargs="*")
"specified ones in order of mention", nargs="*")
parser.set_defaults(handler=handlers.Triggers)
return parser

View File

@ -52,7 +52,7 @@ class ApplicationRepository(ApplicationProperties):
Args:
cache(bool): clear directory with package caches
chroot(bool): clear build chroot
manual(bool): clear directory with manually added packages
manual(bool): clear directory with manually added packages' bases
packages(bool): clear directory with built packages
pacman(bool): clear directory with pacman databases
"""

View File

@ -57,7 +57,7 @@ class Backup(Handler):
@staticmethod
def get_paths(configuration: Configuration) -> Set[Path]:
"""
extract paths to backup
extract paths to back up
Args:
configuration(Configuration): configuration instance

View File

@ -45,6 +45,7 @@ class Handler:
be called directly. The recommended way is to call ``execute`` class method, e.g.::
>>> from ahriman.application.handlers import Add
>>>
>>> Add.execute(args)
"""

View File

@ -139,7 +139,7 @@ class Setup(Handler):
prefix(str): command prefix in {prefix}-{architecture}-build
architecture(str): repository architecture
source(Path): path to source configuration file
multilib(bool): add or do not multilib repository
multilib(bool): add or do not multilib repository to the configuration
repository(str): repository name
paths(RepositoryPaths): repository paths instance
"""

View File

@ -68,7 +68,7 @@ class Pacman(LazyLogging):
Args:
database(DB): pacman database instance to be copied
pacman_root(Path): operating system pacman's root
pacman_root(Path): operating system pacman root
paths(RepositoryPaths): repository paths instance
use_ahriman_cache(bool): use local ahriman cache instead of system one
"""

View File

@ -55,7 +55,7 @@ class Auth(LazyLogging):
def auth_control(self) -> str:
"""
This workaround is required to make different behaviour for login interface.
In case of internal authentication it must provide an interface (modal form) to login with button sends POST
In case of internal authentication it must provide an interface (modal form) to log in with button sends POST
request. But for an external providers behaviour can be different: e.g. OAuth provider requires sending GET
request to external resource

View File

@ -32,7 +32,7 @@ class Mapping(Auth):
user authorization based on mapping from configuration file
Attributes:
salt(str): random generated string to salt passwords
salt(str): random generated string to salted password
database(SQLite): database instance
"""

View File

@ -30,7 +30,7 @@ from ahriman.models.auth_settings import AuthSettings
class OAuth(Mapping):
"""
OAuth user authorization.
OAuth's user authorization.
It is required to create application first and put application credentials.
Attributes:
@ -58,7 +58,7 @@ class OAuth(Mapping):
# thus we expect that address is set
self.redirect_uri = f"""{configuration.get("web", "address")}/api/v1/login"""
self.provider = self.get_provider(configuration.get("auth", "oauth_provider"))
# it is list but we will have to convert to string it anyway
# it is list, but we will have to convert to string it anyway
self.scopes = configuration.get("auth", "oauth_scopes")
@property

View File

@ -33,7 +33,7 @@ from ahriman.models.repository_paths import RepositoryPaths
class Sources(LazyLogging):
"""
helper to download package sources (PKGBUILD etc)
helper to download package sources (PKGBUILD etc...)
Attributes:
DEFAULT_BRANCH(str): (class attribute) default branch to process git repositories.

View File

@ -284,8 +284,8 @@ class Configuration(configparser.RawConfigParser):
# get overrides
specific = self.section_name(section, architecture)
if self.has_section(specific):
# if there is no such section it means that there is no overrides for this arch
# but we anyway will have to delete sections for others archs
# if there is no such section it means that there is no overrides for this arch,
# but we anyway will have to delete sections for others architectures
for key, value in self[specific].items():
self.set_option(section, key, value)
# remove any arch specific section

View File

@ -46,7 +46,7 @@ class LogsOperations(Operations):
for row in connection.execute(
"""
select created, record from logs where package_base = :package_base
order by created asc
order by created
""",
{"package_base": package_base})
]

View File

@ -54,7 +54,7 @@ class Report(LazyLogging):
>>> except Exception as exception:
>>> handle_exceptions(exception)
>>>
>>> report.run([], Result())
>>> report.run(Result(), [])
"""
def __init__(self, architecture: str, configuration: Configuration) -> None:

View File

@ -17,7 +17,7 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
import requests # technically we could use python-telegram-bot, but it is just a single request, cmon
import requests # technically we could use python-telegram-bot, but it is just a single request, c'mon
from typing import Iterable

View File

@ -62,7 +62,7 @@ class WebClient(Client, LazyLogging):
get url for the login api
Returns:
str: full url for web service to login
str: full url for web service to log in
"""
return f"{self.address}/api/v1/login"

View File

@ -154,7 +154,7 @@ def enum_values(enum: Type[Enum]) -> List[str]:
Returns:
List[str]: available enumeration values as string
"""
return [key.value for key in enum]
return [str(key.value) for key in enum] # explicit str conversion for typing
def exception_response_text(exception: requests.exceptions.HTTPError) -> str:
@ -288,7 +288,7 @@ def safe_filename(source: str) -> str:
# https://datatracker.ietf.org/doc/html/rfc3986#section-2.3
# unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
# however we would like to allow some gen-delims characters in filename, because those characters are used
# as delimiter in other URI parts. The ones we allow are
# as delimiter in other URI parts. The ones we allow to are:
# ":" - used as separator in schema and userinfo
# "[" and "]" - used for host part
# "@" - used as separator between host and userinfo

View File

@ -42,7 +42,7 @@ class AURPackage:
description(str): package base description
url(Optional[str]): package upstream URL
num_votes(int): number of votes for the package
polularity(float): package popularity
popularity(float): package popularity
out_of_date(Optional[datetime.datetime]): package out of date timestamp if any
maintainer(Optional[str]): package maintainer
first_submitted(datetime.datetime): timestamp of the first package submission

View File

@ -36,7 +36,7 @@ class PackageSource(str, Enum):
AUR(PackageSource): (class attribute) source is an AUR package for which it should search
Directory(PackageSource): (class attribute) source is a directory which contains packages
Local(PackageSource): (class attribute) source is locally stored PKGBUILD
Remote(PackageSource): (class attribute) source is remote (http, ftp etc) link
Remote(PackageSource): (class attribute) source is remote (http, ftp etc...) link
Repository(PackageSource): (class attribute) source is official repository
Examples:

View File

@ -34,7 +34,7 @@ class SignSettings(str, Enum):
"""
Disabled = "disabled"
Packages = "pacakges"
Packages = "packages"
Repository = "repository"
@classmethod

View File

@ -41,11 +41,11 @@ class User:
Simply create user from database data and perform required validation::
>>> password = User.generate_password(24)
>>> user = User("ahriman", password, UserAccess.Write)
>>> user = User("ahriman", password, UserAccess.Full)
Since the password supplied may be plain text, the ``hash_password`` method can be used to hash the password::
>>> user.password = user.hash_password("salt")
>>> user = user.hash_password("salt")
Having the user instance and password, it can be validated::

View File

@ -101,7 +101,7 @@ class BaseView(View):
get non-empty value from request parameters
Args:
extractor(Callable[[str], T]): function to get value by key
extractor(Callable[[str], T]): function to get value by the specified key
key(str): key to extract value
Returns:

View File

@ -35,6 +35,7 @@ def anyvar(cls: Type[T], strict: bool = False) -> T:
any value helper for mocker calls check
Args:
cls(Type[T]): type of the variable to check
strict(bool, optional): if True then check type of supplied argument (Default value = False)
Returns:

View File

@ -10,7 +10,7 @@ def test_auth_control(auth: Auth) -> None:
must return a control for authorization
"""
assert auth.auth_control
assert "button" in auth.auth_control # I think it should be button
assert "button" in auth.auth_control # I think it should be a button
def test_load_dummy(configuration: Configuration, database: SQLite) -> None:

View File

@ -16,10 +16,10 @@ def test_extend_architectures(mocker: MockerFixture) -> None:
must update available architecture list
"""
mocker.patch("pathlib.Path.is_file", return_value=True)
archs_mock = mocker.patch("ahriman.models.package.Package.supported_architectures", return_value={"x86_64"})
architectures_mock = mocker.patch("ahriman.models.package.Package.supported_architectures", return_value={"x86_64"})
assert Sources.extend_architectures(Path("local"), "i686") == [PkgbuildPatch("arch", list({"x86_64", "i686"}))]
archs_mock.assert_called_once_with(Path("local"))
architectures_mock.assert_called_once_with(Path("local"))
def test_extend_architectures_any(mocker: MockerFixture) -> None:
@ -256,7 +256,7 @@ def test_add_intent_to_add(sources: Sources, mocker: MockerFixture) -> None:
def test_add_skip(sources: Sources, mocker: MockerFixture) -> None:
"""
must skip addition of files to index if no fiels found
must skip addition of files to index if no fields found
"""
mocker.patch("pathlib.Path.glob", return_value=[])
check_output_mock = mocker.patch("ahriman.core.build_tools.sources.Sources._check_output")

View File

@ -63,7 +63,7 @@ def test_run(migrations: Migrations, mocker: MockerFixture) -> None:
def test_run_migration_exception(migrations: Migrations, mocker: MockerFixture) -> None:
"""
must rollback and close cursor on exception during migration
must roll back and close cursor on exception during migration
"""
cursor = MagicMock()
mocker.patch("logging.Logger.info", side_effect=Exception())

View File

@ -3,13 +3,13 @@ from ahriman.core.formatters import AurPrinter
def test_properties(aur_package_ahriman_printer: AurPrinter) -> None:
"""
must return non empty properties list
must return non-empty properties list
"""
assert aur_package_ahriman_printer.properties()
def test_title(aur_package_ahriman_printer: AurPrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert aur_package_ahriman_printer.title() is not None

View File

@ -3,7 +3,7 @@ from ahriman.core.formatters import ConfigurationPrinter
def test_properties(configuration_printer: ConfigurationPrinter) -> None:
"""
must return non empty properties list
must return non-empty properties list
"""
assert configuration_printer.properties()
@ -17,6 +17,6 @@ def test_properties_required(configuration_printer: ConfigurationPrinter) -> Non
def test_title(configuration_printer: ConfigurationPrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert configuration_printer.title() == "[section]"

View File

@ -3,13 +3,13 @@ from ahriman.core.formatters import PackagePrinter
def test_properties(package_ahriman_printer: PackagePrinter) -> None:
"""
must return non empty properties list
must return non-empty properties list
"""
assert package_ahriman_printer.properties()
def test_title(package_ahriman_printer: PackagePrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert package_ahriman_printer.title() is not None

View File

@ -3,7 +3,7 @@ from ahriman.core.formatters import PatchPrinter
def test_properties(patch_printer: PatchPrinter) -> None:
"""
must return non empty properties list
must return non-empty properties list
"""
assert patch_printer.properties()
@ -17,6 +17,6 @@ def test_properties_required(patch_printer: PatchPrinter) -> None:
def test_title(patch_printer: PatchPrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert patch_printer.title() == "ahriman"

View File

@ -10,6 +10,6 @@ def test_properties(status_printer: StatusPrinter) -> None:
def test_title(status_printer: StatusPrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert status_printer.title() is not None

View File

@ -10,6 +10,6 @@ def test_properties(string_printer: StringPrinter) -> None:
def test_title(string_printer: StringPrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert string_printer.title() is not None

View File

@ -10,6 +10,6 @@ def test_properties(update_printer: UpdatePrinter) -> None:
def test_title(update_printer: UpdatePrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert update_printer.title() is not None

View File

@ -3,13 +3,13 @@ from ahriman.core.formatters import UserPrinter
def test_properties(user_printer: UserPrinter) -> None:
"""
must return non empty properties list
must return non-empty properties list
"""
assert user_printer.properties()
def test_title(user_printer: UserPrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert user_printer.title() is not None

View File

@ -10,6 +10,6 @@ def test_properties(version_printer: VersionPrinter) -> None:
def test_title(version_printer: VersionPrinter) -> None:
"""
must return non empty title
must return non-empty title
"""
assert version_printer.title() is not None

View File

@ -20,7 +20,7 @@ def test_load(configuration: Configuration, mocker: MockerFixture) -> None:
def test_load_fallback(configuration: Configuration, mocker: MockerFixture) -> None:
"""
must fallback to stderr without errors
must fall back to stderr without errors
"""
mocker.patch("ahriman.core.log.log.fileConfig", side_effect=PermissionError())
Log.load(configuration, quiet=False, report=False)

View File

@ -5,6 +5,7 @@ from pytest_mock import MockerFixture
from ahriman.core.configuration import Configuration
from ahriman.core.report.html import HTML
from ahriman.models.package import Package
from ahriman.models.result import Result
def test_generate(configuration: Configuration, package_ahriman: Package, mocker: MockerFixture) -> None:
@ -14,5 +15,5 @@ def test_generate(configuration: Configuration, package_ahriman: Package, mocker
write_mock = mocker.patch("pathlib.Path.write_text")
report = HTML("x86_64", configuration, "html")
report.generate([package_ahriman], [])
report.generate([package_ahriman], Result())
write_mock.assert_called_once_with(pytest.helpers.anyvar(int))

View File

@ -17,7 +17,7 @@ def test_leaf_is_root_empty(leaf_ahriman: Leaf) -> None:
def test_leaf_is_root_false(leaf_ahriman: Leaf, leaf_python_schedule: Leaf) -> None:
"""
must be root for empty dependencies list or if does not depend on packages
must be root for empty dependencies list or if it does not depend on packages
"""
assert leaf_ahriman.is_root([leaf_python_schedule])
leaf_ahriman.dependencies = {"ahriman-dependency"}

View File

@ -13,7 +13,7 @@ def test_on_result(trigger: Trigger) -> None:
def test_on_result_run(trigger: Trigger) -> None:
"""
must fallback to run method if it exists
must fall back to run method if it exists
"""
run_mock = MagicMock()
setattr(trigger, "run", run_mock)

View File

@ -59,7 +59,7 @@ def test_asset_upload_with_removal(github: Github, github_release: Dict[str, Any
def test_asset_upload_empty_mimetype(github: Github, github_release: Dict[str, Any], mocker: MockerFixture) -> None:
"""
must upload asset to the repository with empty mime type if cannot guess it
must upload asset to the repository with empty mime type if the library cannot guess it
"""
mocker.patch("pathlib.Path.open", return_value=b"")
mocker.patch("ahriman.core.upload.github.Github.asset_remove")

View File

@ -22,8 +22,8 @@ def _get_owner(root: Path, same: bool) -> Callable[[Path], Tuple[int, int]]:
Callable[[Path], Tuple[int, int]]: function which can define ownership
"""
root_owner = (42, 42)
nonroot_owner = (42, 42) if same else (1, 1)
return lambda path: root_owner if path == root else nonroot_owner
non_root_owner = (42, 42) if same else (1, 1)
return lambda path: root_owner if path == root else non_root_owner
def test_root_owner(repository_paths: RepositoryPaths, mocker: MockerFixture) -> None:

View File

@ -177,7 +177,7 @@ async def test_auth_handler_write(mocker: MockerFixture) -> None:
def test_setup_auth(application_with_auth: web.Application, auth: Auth, mocker: MockerFixture) -> None:
"""
must setup authorization
must set up authorization
"""
setup_mock = mocker.patch("aiohttp_security.setup")
application = setup_auth(application_with_auth, auth)

View File

@ -6,7 +6,7 @@ from ahriman.web.routes import setup_routes
def test_setup_routes(application: web.Application, configuration: Configuration) -> None:
"""
must generate non empty list of routes
must generate non-empty list of routes
"""
setup_routes(application, configuration.getpath("web", "static_path"))
assert application.router.routes()

View File

@ -62,7 +62,7 @@ async def test_get(client: TestClient, package_ahriman: Package) -> None:
assert logs["logs"] == "[1970-01-01 00:00:42] message"
async def test_get_not_foud(client: TestClient, package_ahriman: Package) -> None:
async def test_get_not_found(client: TestClient, package_ahriman: Package) -> None:
"""
must return not found for missing package
"""

View File

@ -51,7 +51,7 @@ async def test_get_redirect_to_oauth_empty_code(client_with_oauth_auth: TestClie
async def test_get(client_with_oauth_auth: TestClient, mocker: MockerFixture) -> None:
"""
must login user correctly from OAuth
must log in user correctly from OAuth
"""
oauth = client_with_oauth_auth.app["validator"]
oauth.get_oauth_username.return_value = "user"
@ -86,7 +86,7 @@ async def test_get_unauthorized(client_with_oauth_auth: TestClient, mocker: Mock
async def test_post(client_with_auth: TestClient, user: User, mocker: MockerFixture) -> None:
"""
must login user correctly
must log in user correctly
"""
payload = {"username": user.username, "password": user.password}
remember_mock = mocker.patch("aiohttp_security.remember")

View File

@ -19,7 +19,7 @@ async def test_get_permission() -> None:
async def test_post(client_with_auth: TestClient, mocker: MockerFixture) -> None:
"""
must logout user correctly
must log out user correctly
"""
mocker.patch("aiohttp_security.check_authorized")
forget_mock = mocker.patch("aiohttp_security.forget")