Skip to content

Commit

Permalink
Rewrite introduction to the README
Browse files Browse the repository at this point in the history
  • Loading branch information
@JakobGM
JakobGM committed May 4, 2018
1 parent 589b228 commit 1561fab
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 42 deletions.
85 changes: 43 additions & 42 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,35 @@
|logo| Astrality - A Dynamic Configuration File Manager |pypi_version| |travis-ci| |rtfd| |coveralls| |gitter|
==============================================================================================================

Astrality is the "dotfile"-manager you wish you always had.
TL;DR: Automatically deploy dotfiles. Grouped into modules with dynamic behaviour.

What does it do?
================

Astrality offers an `Ansible <https://www.ansible.com/>`_-like approach to dotfile management that adapts to your existing dotfiles structure, not the other way around.
You can start to write configuration files as templates which will be *automatically* compiled to their intended location when they are modified.
Astrality allows you symlink/copy/compile files and templates from directories
according to a central configuration file. Tasks to be performed are grouped
into modules which can be conditionally enabled, based on installed programs,
OS, environment variables, and so on.

Templating allows more flexibility when writing otherwise static configuration files, replacing placeholders with values defined in a central configuration file.
Astrality builds upon this by allowing you to dynamically manipulate the context store, changing configuration files based on the current OS, the time of day, and much more.
You can also write configuration files as `Jinja2 templates
<http://jinja.pocoo.org/docs/2.10/templates/>`_. Placeholders will be replaced
with pre-defined context values. Astrality builds upon this by allowing you to
dynamically manipulate the context store, changing configuration files based on
the current OS, the time of day, and much more.

By publishing an Astrality module to GitHub, others can try out your configuration by only pasting one line into their configuration. The use of template placeholders in your configuration files make such sharing portable on cross of different systems and user preferences.
When dotfiles are modified, Astrality will automatically
re-(symlink|copy|compile) those files.

Take a look at the `full documentation <https://astrality.readthedocs.io>`_ for more information, and feel free to drop by our `Gitter room <https://gitter.im/astrality/Lobby>`_ for any questions you might have.
Astrality modules can be fetched from GitHub, making configuration sharing
easy. The use of template placeholders make such sharing portable on cross of
different systems and user preferences.

Take a look at `the tutorial
<http://astrality.readthedocs.io/en/latest/tutorial.html>`_ for managing a
dotfile repository, or see the `full documentation
<https://astrality.readthedocs.io>`_ for all available functionality.
Feel free to drop by our `Gitter room <https://gitter.im/astrality/Lobby>`_ when
getting started.

**Here is gif demonstrating how Astrality is used to**:

Expand All @@ -49,39 +64,23 @@ Take a look at the `full documentation <https://astrality.readthedocs.io>`_ for

.. image:: https://user-images.githubusercontent.com/10655778/36535609-934488ec-17ca-11e8-860e-4af5e1464997.gif

**Possible use cases are:**

* Create a single source of truth for configuration options. Change your preferred font type or color scheme, and see that change be applied across several different graphical applications.
* Receive rapid feedback when editing configuration files by specifying commands to run when specific configuration files are modified.
* Conditionally copy (or compile) configuration files to specific paths. For example, only copy `neovim's <https://neovim.io/>`_ configuration if it is available on the system.
* Configure dynamic behaviour for applications that do not support it. For example, set your desktop wallpaper based on the sun's position in the sky at your location.
* Couple configurations across your applications. When you change your desktop wallpaper, automatically change the font type and color of your `conky modules <https://github.com/brndnmtthws/conky>`_.
* Insert environment variables, by writing ``{{ env.USER }}``, and command substitutions, by writing ``{{ 'xrandr | grep -cw connected' | shell }}``), into configuration files that do not natively support them.
* Modularize your desktop configuration, allowing you to switch between different combinations of applications and/or configurations by only editing one line. With Astrality you can, for example, quickly switch between `different <https://github.com/jaagr/polybar>`_ `status <https://github.com/LemonBoy/bar>`_ `bars <https://i3wm.org/i3bar/>`_ with little effort.
* Share ``modules`` with others who can effortlessly try out your configuration, and easily switch back to their old configuration if they wish, making experimentation frictionless.
* And much more... An `example configuration <http://astrality.readthedocs.io/en/latest/example_configuration.html>`_ with several examples is included.

The configuration format uses the flexible `YAML <http://docs.ansible.com/ansible/latest/YAMLSyntax.html#yaml-basics>`_ format, and the template language uses the `Jinja2 syntax <http://jinja.pocoo.org/docs/2.10/>`_, which is easy to get started with, but allows complex templating for those who need it.

It is relatively easy to create ``modules`` to your own liking. Pull requests with new example modules are welcome.

Getting started
===============

Prerequisites
-------------
Astrality requires `python 3.6 <https://www.python.org/downloads/>`_ or greater. Make sure to install it if you do not already have it:

.. code-block:: console
# Example installation on ArchLinux
$ sudo pacman -Syu python
Astrality requires `python 3.6 <https://www.python.org/downloads/>`_ or
greater. Check your version by running ``python --version``.

Installation
------------

Create a new `virtualenv <https://virtualenv.pypa.io/en/stable/>`_ for python 3.6 (or use your system python 3.6 if you prefer). Install Astrality from `pypi <https://pypi.org/project/astrality/>`_ like so:
``astrality-git`` is published on the `AUR <https://aur.archlinux.org/>`_ for
ArchLinux users. Otherwise, you can install Astrality using ``pip``:

Create a new `virtualenv <https://virtualenv.pypa.io/en/stable/>`_ for python
3.6 (or use your system python 3.6 if you prefer). Install Astrality from `pypi
<https://pypi.org/project/astrality/>`_ like so:

.. code-block:: console
Expand All @@ -101,20 +100,22 @@ And now start `astrality`:
If you have ``feh`` installed, your desktop wallpaper should now be changed according to the sun's position in the sky at `Null Island <https://en.wikipedia.org/wiki/Null_Island>`_. Since you probably don't live there, you should now configure Astrality.

Optional dependencies
---------------------
The included example configuration for Astrality contains modules which are dependent on `conky <https://wiki.archlinux.org/index.php/Conky>`_ and `feh <https://wiki.archlinux.org/index.php/feh>`_. These modules are automatically disabled if their dependencies are not satisfied.
If you want to use them, you should install ``conky`` and ``feh``. An example installation on ArchLinux would be:

.. code-block:: console
Use cases
=========

$ sudo pacman -Syu conky feh
The default configuration also uses the `Nerd Font <https://github.com/ryanoasis/nerd-fonts>`_ "FuraCode Nerd Font". Install it if you don't change the font in your configuration. On ArchLinux, it can be installed with the ``nerd-fonts-complete`` AUR package:
* Create a single source of truth for configuration options. Change your preferred font type or color scheme, and see that change be applied across several different graphical applications.
* Receive rapid feedback when editing configuration files by specifying commands to run when specific configuration files are modified.
* Conditionally copy (or compile) configuration files to specific paths. For example, only copy `neovim's <https://neovim.io/>`_ configuration if it is available on the system.
* Configure dynamic behaviour for applications that do not support it. For example, set your desktop wallpaper based on the sun's position in the sky at your location.
* Couple configurations across your applications. When you change your desktop wallpaper, automatically change the font type and color of your `conky modules <https://github.com/brndnmtthws/conky>`_.
* Insert environment variables, by writing ``{{ env.USER }}``, and command substitutions, by writing ``{{ 'xrandr | grep -cw connected' | shell }}``), into configuration files that do not natively support them.
* Modularize your desktop configuration, allowing you to switch between different combinations of applications and/or configurations by only editing one line. With Astrality you can, for example, quickly switch between `different <https://github.com/jaagr/polybar>`_ `status <https://github.com/LemonBoy/bar>`_ `bars <https://i3wm.org/i3bar/>`_ with little effort.
* Share ``modules`` with others who can effortlessly try out your configuration, and easily switch back to their old configuration if they wish, making experimentation frictionless.
* And much more... An `example configuration <http://astrality.readthedocs.io/en/latest/example_configuration.html>`_ with several examples is included.

.. code-block:: console
The configuration format uses the flexible `YAML <http://docs.ansible.com/ansible/latest/YAMLSyntax.html#yaml-basics>`_ format, and the template language uses the `Jinja2 syntax <http://jinja.pocoo.org/docs/2.10/>`_, which is easy to get started with, but allows complex templating for those who need it.

$ yaourt -S nerd-fonts-complete
It is relatively easy to create ``modules`` to your own liking. Pull requests with new example modules are welcome.

Configuration and further documentation
---------------------------------------
Expand Down
2 changes: 2 additions & 0 deletions astrality/config/context.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ fonts:
#
# Here we define the main fonts used across our applications. Where 1
# is the primary font, 2 the secondary font, and so on.

# These fonts can be installed here: https://nerdfonts.com/
1:
name: FuraCode Nerd Font
size: 8
Expand Down

0 comments on commit 1561fab

Please sign in to comment.