[entropy.server] move Makefile logic to server/, add man support to eit, move matter to server/

.gitignore

@@ -2,4 +2,5 @@
 *.pyo
 misc/po/*.mo
 *.directory
+server/doc/man/*.1
 #*#

Makefile

@@ -1,6 +1,6 @@
 PKGNAME = entropy
 PYTHON = python2
-SUBDIRS = magneto misc/po sulfur
+SUBDIRS = server magneto misc/po sulfur
 SERVER_INSPKGS = reagent.py activator.py server_reagent.py server_activator.py server_query.py
 PREFIX = /usr
 BINDIR = $(PREFIX)/bin
@@ -48,21 +48,6 @@ entropy-install:
 
 	install -m 644 docs/COPYING $(DESTDIR)/$(LIBDIR)/entropy/
 
-entropy-server-install:
-
-	mkdir -p $(DESTDIR)/$(LIBDIR)/entropy/server
-	mkdir -p $(DESTDIR)/etc/entropy
-	mkdir -p $(DESTDIR)$(PREFIX)/sbin
-	mkdir -p $(DESTDIR)$(BINDIR)
-
-	install -m 644 conf/server.conf.example $(DESTDIR)/etc/entropy/
-
-	install -m 755 server/*.py $(DESTDIR)/$(LIBDIR)/entropy/server/
-	install -m 755 server/*.py $(DESTDIR)/$(LIBDIR)/entropy/server/
-	cp server/eit $(DESTDIR)/$(LIBDIR)/entropy/server/ -Ra
-	mv $(DESTDIR)/$(LIBDIR)/entropy/server/eit.py $(DESTDIR)$(BINDIR)/eit
-	install -m 755 services/matter $(DESTDIR)$(PREFIX)/sbin
-
 equo-install:
 
 	mkdir -p $(DESTDIR)/$(LIBDIR)/entropy/client
@@ -101,5 +86,5 @@ updates-daemon-install:
 	install -m 644 misc/dbus/system-services/org.entropy.Client.service $(DESTDIR)$(PREFIX)/share/dbus-1/system-services/
 	install -m 644 misc/dbus/interfaces/org.entropy.Client.xml $(DESTDIR)$(PREFIX)/share/dbus-1/interfaces/
 
-install: all entropy-install entropy-server-install equo-install updates-daemon-install
+install: all entropy-install equo-install updates-daemon-install
 	for d in $(SUBDIRS); do $(MAKE) -C $$d install; done

server/Makefile

@@ -0,0 +1,26 @@
+PKGNAME = entropy
+SUBDIRS = doc
+PREFIX = /usr
+BINDIR = $(PREFIX)/bin
+LIBDIR = $(PREFIX)/lib
+DESTDIR = 
+
+all:
+	for d in $(SUBDIRS); do $(MAKE) -C $$d; done
+
+install:
+	mkdir -p $(DESTDIR)$(LIBDIR)/entropy/server
+	mkdir -p $(DESTDIR)/etc/entropy
+	mkdir -p $(DESTDIR)$(PREFIX)/sbin
+	mkdir -p $(DESTDIR)$(BINDIR)
+
+	install -m 644 ../conf/server.conf.example $(DESTDIR)/etc/entropy/
+
+	install -m 755 *.py $(DESTDIR)/$(LIBDIR)/entropy/server/
+	mv $(DESTDIR)/$(LIBDIR)/entropy/server/eit.py $(DESTDIR)$(BINDIR)/eit
+	install -m 755 matter $(DESTDIR)$(PREFIX)/sbin
+
+	for d in $(SUBDIRS); do $(MAKE) -C $$d install; done
+
+clean:
+	for d in $(SUBDIRS); do $(MAKE) -C $$d clean; done

server/doc/Makefile

@@ -0,0 +1,21 @@
+EITVER = 1.0
+PREFIX = /usr
+BINDIR = $(PREFIX)/bin
+LIBDIR = $(PREFIX)/lib
+DESTDIR = 
+
+all:
+	rm man/* -r && \
+	for man_name in mansrc/*.1.txt; do \
+		a2x --attribute="eitversion=$(EITVER)" --format=manpage \
+		-D man/ $$man_name; \
+	done
+
+update-doc:
+	./generate
+
+install:
+	mkdir -p $(DESTDIR)$(PREFIX)/share/man/man1
+	install -m 644 man/* $(DESTDIR)$(PREFIX)/share/man/man1/
+
+clean:

server/doc/generate

@@ -0,0 +1,184 @@
+#!/usr/bin/python2
+import sys
+import os
+os.environ['LANGUAGE'] = "en_US.UTF-8"
+os.environ['LC_ALL'] = "en_US.UTF-8"
+os.environ['LANG'] = "en_US.UTF-8"
+import codecs
+
+sys.path.insert(0, "../")
+
+from eit.commands.descriptor import EitCommandDescriptor
+
+MAN_HEADER="""\
+EIT(1)
+======
+:man source:   eit {eitversion}
+:man manual:   eit {eitversion}
+
+
+NAME
+----
+eit - Entropy Infrastructure Toolkit.
+
+
+SYNOPSIS
+--------
+*eit* [command] [command options]
+
+
+INTRODUCTION
+------------
+Eit is a tool for creating, managing and tracking Entropy repositories.
+It is highly inspired to the "Git" way of doing things (add, commit,
+checkout, etc) and puts ease of use on top of its priorities.
+With this tool, anybody can create his/her own repository and serve
+users custom packages or even a whole full-featured repository living
+inside a dedicated chroot!
+
+
+USAGE
+-----
+Eit has a modular design, commands can be added and removed in a pluggable
+way. There are however a set of built-in commands that are shipped with
+the default Eit distribution.
+
+
+OPTIONS
+-------
+*--help*::
+    Show Eit Help, listing all the runtime available commands.
+
+
+COMMANDS
+--------
+---commands---
+
+
+AUTHORS
+-------
+Eit has been accidentally prototyped during a rainy Sunday by Fabio
+Erculiani who was looking for innovative ways of handling package
+bumps in Sabayon Entropy repositories.
+A few months later, Eit saw the light.
+
+
+REPORTING BUGS
+--------------
+Report bugs to https://bugs.sabayon.org or directly to the author at
+lxnay@sabayon.org.
+
+SEE ALSO
+--------
+---also_commands---
+"""
+
+SPLIT_MAN="""\
+%(name)s(1)
+%(title)s
+:man source:   eit {eitversion}
+:man manual:   eit {eitversion}
+
+
+NAME
+----
+%(name)s - %(description)s
+
+
+SYNOPSIS
+--------
+%(synopsis)s
+
+
+INTRODUCTION
+------------
+%(introduction)s
+
+
+OPTIONS
+-------
+%(options)s
+
+
+AUTHORS
+-------
+Eit has been accidentally prototyped during a rainy Sunday by Fabio
+Erculiani who was looking for innovative ways of handling package
+bumps in Sabayon Entropy repositories.
+A few months later, Eit saw the light.
+
+
+REPORTING BUGS
+--------------
+Report bugs to https://bugs.sabayon.org or directly to the author at
+lxnay@sabayon.org.
+
+SEE ALSO
+--------
+    eit(1)%(seealso)s
+"""
+
+
+descriptors = EitCommandDescriptor.obtain()
+descriptors.sort(key = lambda x: x.get_name())
+
+commands_txt = []
+see_also_txt = []
+split_mans = []
+for descriptor in descriptors:
+    klass = descriptor.get_class()
+    name = descriptor.get_name()
+    aliases = klass.ALIASES
+    aliases_str = ", ".join(aliases)
+    if aliases_str:
+        aliases_str = " [%s]" % (aliases_str,)
+    command_txt = "%s%s%s%s" % ("*", name, aliases_str, "*::")
+    desc = descriptor.get_description()
+    command_txt += "\n    %s\n" % (desc,)
+    commands_txt.append(command_txt)
+    try:
+        man = klass([]).man()
+    except NotImplementedError:
+        man = None
+    if man is not None:
+        man['name'] = "eit-" + man['name']
+        see_also_txt.append("%s(1)" % (man['name'],))
+        man['title'] = "="*(len(man['name']) + 3)
+        if "seealso" not in man:
+            man['seealso'] = ""
+        else:
+            man['seealso'] = ", " + man['seealso']
+        man_txt = SPLIT_MAN % man
+        split_mans.append((man['name'], man_txt))
+
+if not see_also_txt:
+    see_also_txt.append("Nothing")
+man_txt = MAN_HEADER[:]
+man_txt = man_txt.replace("---commands---", "\n".join(commands_txt))
+
+see_also = ""
+orig_count = 5
+count = orig_count
+see_also_buf = []
+for entry in see_also_txt:
+    if count == 0:
+        count = orig_count
+        see_also += ", ".join(see_also_buf)
+        see_also += "\n    "
+        del see_also_buf[:]
+    count -= 1
+    see_also_buf.append(entry)
+if see_also_buf:
+    see_also += ", ".join(see_also_buf)
+    see_also += "\n    "
+
+man_txt = man_txt.replace("---also_commands---", "    " + see_also)
+sys.stdout.write("generating mansrc/eit.1.txt\n")
+with codecs.open("mansrc/eit.1.txt", "w", encoding="UTF-8") as man_f:
+    man_f.write(man_txt)
+
+for man_name, man_txt in split_mans:
+    sys.stdout.write("generating mansrc/%s.1.txt\n" % (man_name,))
+    with codecs.open("mansrc/%s.1.txt" % (man_name,), "w",
+         encoding="UTF-8") as man_f:
+         man_f.write(man_txt)

server/doc/mansrc/eit-add.1.txt

@@ -0,0 +1,66 @@
+eit-add(1)
+==========
+:man source:   eit {eitversion}
+:man manual:   eit {eitversion}
+
+
+NAME
+----
+eit-add - commit to repository the provided packages
+
+
+SYNOPSIS
+--------
+eit add [-h] [--to <repository>] [--quick] <package> [<package> ...]
+
+
+INTRODUCTION
+------------
+Selectively add unstaged packages to repository.
+If you are familiar with git, this maps to *git commit <path>*.
+Packages in the repository sharing the same scope are going to
+be replaced, unless marked as (manually) injected.
+Entropy package scope is given by the following tuple:
+    (*package key*, *package slot*, *package tag*)
+
+
+
+OPTIONS
+-------
+"eit add" supports the following options which alters its behaviour.
+
+
+POSITIONAL ARGUMENTS
+~~~~~~~~~~~~~~~~~~~~
+*<package>*::
+    package names
+
+OPTIONAL ARGUMENTS
+~~~~~~~~~~~~~~~~~~
+*--help*::
+    show this help message and exit
+
+*--to*=<repository>::
+    add to given repository
+
+*--quick*::
+    no stupid questions
+
+
+
+AUTHORS
+-------
+Eit has been accidentally prototyped during a rainy Sunday by Fabio
+Erculiani who was looking for innovative ways of handling package
+bumps in Sabayon Entropy repositories.
+A few months later, Eit saw the light.
+
+
+REPORTING BUGS
+--------------
+Report bugs to https://bugs.sabayon.org or directly to the author at
+lxnay@sabayon.org.
+
+SEE ALSO
+--------
+    eit(1), eit-commit(1), eit-repack(1)

server/doc/mansrc/eit-commit.1.txt

@@ -0,0 +1,66 @@
+eit-commit(1)
+=============
+:man source:   eit {eitversion}
+:man manual:   eit {eitversion}
+
+
+NAME
+----
+eit-commit - commit changes to repository
+
+
+SYNOPSIS
+--------
+eit commit [-h] [--interactive] [--quick] [<repo>]
+
+
+INTRODUCTION
+------------
+Committing to a repository means adding all the unstaged packages
+to the same. Unstaged packages are those packages that have just
+been compiled but not yet added to any repository.
+If you are familiar with git, this maps to *git commit -a*.
+If you would like to selectively add certain packages, please see
+*eit-add*(1).
+
+
+
+OPTIONS
+-------
+"eit commit" supports the following options which alters its behaviour.
+
+
+POSITIONAL ARGUMENTS
+~~~~~~~~~~~~~~~~~~~~
+*<repo>*::
+    repository
+
+OPTIONAL ARGUMENTS
+~~~~~~~~~~~~~~~~~~
+*--help*::
+    show this help message and exit
+
+*--interactive*::
+    selectively pick changes
+
+*--quick*::
+    no stupid questions
+
+
+
+AUTHORS
+-------
+Eit has been accidentally prototyped during a rainy Sunday by Fabio
+Erculiani who was looking for innovative ways of handling package
+bumps in Sabayon Entropy repositories.
+A few months later, Eit saw the light.
+
+
+REPORTING BUGS
+--------------
+Report bugs to https://bugs.sabayon.org or directly to the author at
+lxnay@sabayon.org.
+
+SEE ALSO
+--------
+    eit(1), eit-add(1), eit-repack(1)

server/doc/mansrc/eit-repack.1.txt

@@ -0,0 +1,61 @@
+eit-repack(1)
+=============
+:man source:   eit {eitversion}
+:man manual:   eit {eitversion}
+
+
+NAME
+----
+eit-repack - rebuild packages in repository
+
+
+SYNOPSIS
+--------
+eit repack [-h] [--in <repository>] <package> [<package> ...]
+
+
+INTRODUCTION
+------------
+Recrate the whole Entropy package from live system through
+the Source Package Manager. This allows the latter to regenerate
+its metadata (useful in case of dependency changes).
+The package must be already available in the queried repository.
+
+
+
+OPTIONS
+-------
+"eit repack" supports the following options which alters its behaviour.
+
+
+POSITIONAL ARGUMENTS
+~~~~~~~~~~~~~~~~~~~~
+*<package>*::
+    package names
+
+OPTIONAL ARGUMENTS
+~~~~~~~~~~~~~~~~~~
+*--help*::
+    show this help message and exit
+
+*--in*=<repository>::
+    repack to given repository
+
+
+
+AUTHORS
+-------
+Eit has been accidentally prototyped during a rainy Sunday by Fabio
+Erculiani who was looking for innovative ways of handling package
+bumps in Sabayon Entropy repositories.
+A few months later, Eit saw the light.
+
+
+REPORTING BUGS
+--------------
+Report bugs to https://bugs.sabayon.org or directly to the author at
+lxnay@sabayon.org.
+
+SEE ALSO
+--------
+    eit(1), eit-add(1), eit-commit(1)

server/doc/mansrc/eit.1.txt

@@ -0,0 +1,165 @@
+EIT(1)
+======
+:man source:   eit {eitversion}
+:man manual:   eit {eitversion}
+
+
+NAME
+----
+eit - Entropy Infrastructure Toolkit.
+
+
+SYNOPSIS
+--------
+*eit* [command] [command options]
+
+
+INTRODUCTION
+------------
+Eit is a tool for creating, managing and tracking Entropy repositories.
+It is highly inspired to the "Git" way of doing things (add, commit,
+checkout, etc) and puts ease of use on top of its priorities.
+With this tool, anybody can create his/her own repository and serve
+users custom packages or even a whole full-featured repository living
+inside a dedicated chroot!
+
+
+USAGE
+-----
+Eit has a modular design, commands can be added and removed in a pluggable
+way. There are however a set of built-in commands that are shipped with
+the default Eit distribution.
+
+
+OPTIONS
+-------
+*--help*::
+    Show Eit Help, listing all the runtime available commands.
+
+
+COMMANDS
+--------
+*add*::
+    commit to repository the provided packages
+
+*branch*::
+    manage repository branches
+
+*bump*::
+    bump repository revision, force push
+
+*checkout [co]*::
+    switch from a repository to another
+
+*cleanup [cn, clean]*::
+    clean expired packages from a repository
+
+*commit [ci]*::
+    commit changes to repository
+
+*cp*::
+    copy packages from a repository to another
+
+*deps*::
+    edit dependencies for packages in repository
+
+*files [f]*::
+    show files owned by packages
+
+*graph*::
+    show dependency graph for packages
+
+*help [-h, --help]*::
+    this help
+
+*init*::
+    initialize repository (erasing all its content)
+
+*inject [fit]*::
+    inject package files into repository
+
+*key*::
+    manage repository GPG keys
+
+*list*::
+    show repository content (packages)
+
+*lock*::
+    lock repository
+
+*log*::
+    show log for repository
+
+*match*::
+    match packages in repositories
+
+*merge*::
+    merge branch into current
+
+*mv*::
+    move packages from a repository to another
+
+*notice*::
+    manage repository notice-board
+
+*own*::
+    search packages owning paths
+
+*pkgmove*::
+    edit automatic package moves for repository
+
+*push [pull, sync]*::
+    push (or pull) repository packages and metadata
+
+*query [q]*::
+    miscellaneous package metadata queries
+
+*remove [rm]*::
+    remove packages from repository
+
+*repack [rp]*::
+    rebuild packages in repository
+
+*repo*::
+    show current repository
+
+*reset*::
+    reset repository to remote status
+
+*revgraph*::
+    show reverse dependency graph for packages
+
+*search*::
+    search packages in repositories
+
+*status [st]*::
+    show repository status
+
+*test*::
+    run QA tests
+
+*unlock*::
+    unlock repository
+
+*vacuum*::
+    clean expired/removed packages from repository
+
+
+
+AUTHORS
+-------
+Eit has been accidentally prototyped during a rainy Sunday by Fabio
+Erculiani who was looking for innovative ways of handling package
+bumps in Sabayon Entropy repositories.
+A few months later, Eit saw the light.
+
+
+REPORTING BUGS
+--------------
+Report bugs to https://bugs.sabayon.org or directly to the author at
+lxnay@sabayon.org.
+
+SEE ALSO
+--------
+    eit-add(1), eit-commit(1), eit-repack(1)
+    

server/eit/commands/add.py

@@ -27,6 +27,16 @@ class EitAdd(EitCommit):
     NAME = "add"
     ALIASES = []
 
+    INTRODUCTION = """\
+Selectively add unstaged packages to repository.
+If you are familiar with git, this maps to *git commit <path>*.
+Packages in the repository sharing the same scope are going to
+be replaced, unless marked as (manually) injected.
+Entropy package scope is given by the following tuple:
+    (*package key*, *package slot*, *package tag*)
+"""
+    SEE_ALSO = "eit-commit(1), eit-repack(1)"
+
     def _get_parser(self):
         """ Overridden from EitCommit """
         descriptor = EitCommandDescriptor.obtain_descriptor(

server/eit/commands/command.py

@@ -67,6 +67,16 @@ class EitCommand(object):
         """
         raise NotImplementedError()
 
+    def man(self):
+        """
+        Return a dictionary containing the following man
+        entries (in a2x format), excluding the entry title:
+        name, synopsis, introduction, options.
+        Optional keys are: seealso.
+        All of them are mandatory.
+        """
+        raise NotImplementedError()
+
     def _entropy(self, *args, **kwargs):
         """
         Return the Entropy Server object.

server/eit/commands/commit.py

@@ -95,6 +95,67 @@ class EitCommit(EitCommand):
         sys.stdout.write(" ".join(outcome) + "\n")
         sys.stdout.flush()
 
+    INTRODUCTION = """\
+Committing to a repository means adding all the unstaged packages
+to the same. Unstaged packages are those packages that have just
+been compiled but not yet added to any repository.
+If you are familiar with git, this maps to *git commit -a*.
+If you would like to selectively add certain packages, please see
+*eit-add*(1).
+"""
+    SEE_ALSO = "eit-add(1), eit-repack(1)"
+
+    def man(self):
+        """
+        Overridden from EitCommand.
+        """
+        parser = self._get_parser()
+        prog = "%s %s" % ("eit", self.NAME)
+        formatter = parser.formatter_class(prog=prog)
+        usage = formatter._format_usage(parser.usage,
+                            parser._actions,
+                            parser._mutually_exclusive_groups,
+                            "").rstrip()
+
+        options_txt = []
+        action_groups = parser._action_groups
+        if action_groups:
+            options_header = "\"eit " + self.NAME + "\" "
+            options_header += "supports the following options which "
+            options_header += "alters its behaviour.\n\n"
+            options_txt.append(options_header)
+
+        for group in action_groups:
+            options_txt.append(group.title.upper())
+            options_txt.append("~" * len(group.title))
+            for action in group._group_actions:
+                action_name = action.metavar
+
+                option_strings = action.option_strings
+                if not option_strings:
+                    # positional args
+                    action_str = "*" + action_name + "*::\n"
+                    action_str += "    " + action.help + "\n"
+                else:
+                    action_str = ""
+                    for option_str in option_strings:
+                        action_str = "*" + option_str + "*"
+                        if action_name:
+                            action_str += "=" + action_name
+                        action_str += "::\n"
+                        action_str += "    " + action.help + "\n"
+                options_txt.append(action_str)
+
+        data = {
+            'name': self.NAME,
+            'description': parser.description,
+            'introduction': self.INTRODUCTION,
+            'seealso': self.SEE_ALSO,
+            'synopsis': usage,
+            'options': "\n".join(options_txt),
+        }
+        return data
+
     def parse(self):
         parser = self._get_parser()
         try:

server/eit/commands/help.py

@@ -47,7 +47,7 @@ class EitHelp(EitCommand):
             if name == EitHelp.NAME:
                 # do not add self
                 continue
-            outcome.append(descriptor.get_name())
+            outcome.append(name)
             aliases = descriptor.get_class().ALIASES
             outcome.extend(aliases)
 

server/eit/commands/repack.py

@@ -26,6 +26,14 @@ class EitRepack(EitCommit):
     NAME = "repack"
     ALIASES = ["rp"]
 
+    INTRODUCTION = """\
+Recrate the whole Entropy package from live system through
+the Source Package Manager. This allows the latter to regenerate
+its metadata (useful in case of dependency changes).
+The package must be already available in the queried repository.
+"""
+    SEE_ALSO = "eit-add(1), eit-commit(1)"
+
     def _get_parser(self):
         """ Overridden from EitCommit """
         descriptor = EitCommandDescriptor.obtain_descriptor(