allura-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From brond...@apache.org
Subject [14/16] allura git commit: [#6373] document common admin scripts
Date Tue, 07 Jul 2015 22:11:31 GMT
[#6373] document common admin scripts


Project: http://git-wip-us.apache.org/repos/asf/allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/allura/commit/053627a6
Tree: http://git-wip-us.apache.org/repos/asf/allura/tree/053627a6
Diff: http://git-wip-us.apache.org/repos/asf/allura/diff/053627a6

Branch: refs/heads/db/6373
Commit: 053627a6060193fc4f7080494a82faa1cc3805e5
Parents: 93a1ecc
Author: Dave Brondsema <dave@brondsema.net>
Authored: Wed Jul 1 12:49:45 2015 -0400
Committer: Dave Brondsema <dave@brondsema.net>
Committed: Tue Jul 7 18:10:57 2015 -0400

----------------------------------------------------------------------
 Allura/allura/scripts/disable_users.py         |   3 +
 Allura/allura/scripts/refreshrepo.py           |   4 +
 Allura/allura/scripts/reindex_projects.py      |   6 +-
 Allura/allura/scripts/reindex_users.py         |   6 +-
 Allura/docs/conf.py                            |   3 +-
 Allura/docs/getting_started/administration.rst | 126 +++++++++++++++++---
 requirements.txt                               |   1 +
 scripts/create-allura-sitemap.py               |   7 +-
 scripts/publicize-neighborhood.py              |   9 +-
 scripts/scrub-allura-data.py                   |  13 +-
 10 files changed, 151 insertions(+), 27 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/Allura/allura/scripts/disable_users.py
----------------------------------------------------------------------
diff --git a/Allura/allura/scripts/disable_users.py b/Allura/allura/scripts/disable_users.py
index 7eeef33..ed93833 100644
--- a/Allura/allura/scripts/disable_users.py
+++ b/Allura/allura/scripts/disable_users.py
@@ -66,5 +66,8 @@ class DisableUsers(ScriptTask):
         return parser
 
 
+def get_parser():
+    return DisableUsers.parser()
+
 if __name__ == '__main__':
     DisableUsers.main()

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/Allura/allura/scripts/refreshrepo.py
----------------------------------------------------------------------
diff --git a/Allura/allura/scripts/refreshrepo.py b/Allura/allura/scripts/refreshrepo.py
index a336b0d..fbec016 100644
--- a/Allura/allura/scripts/refreshrepo.py
+++ b/Allura/allura/scripts/refreshrepo.py
@@ -194,6 +194,10 @@ class RefreshRepo(ScriptTask):
         return parser
 
 
+def get_parser():
+    return RefreshRepo.parser()
+
+
 if __name__ == '__main__':
     faulthandler.enable()
     RefreshRepo.main()

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/Allura/allura/scripts/reindex_projects.py
----------------------------------------------------------------------
diff --git a/Allura/allura/scripts/reindex_projects.py b/Allura/allura/scripts/reindex_projects.py
index 89c447e..0f8f3be 100644
--- a/Allura/allura/scripts/reindex_projects.py
+++ b/Allura/allura/scripts/reindex_projects.py
@@ -87,7 +87,7 @@ class ReindexProjects(ScriptTask):
 
     @classmethod
     def parser(cls):
-        parser = argparse.ArgumentParser(description='Reindex all projects')
+        parser = argparse.ArgumentParser(description='Reindex all project records into Solr
(for searching)')
         parser.add_argument('-n', '--nbhd', action='store', default='', dest='nbhd',
                             help='Restrict reindex to a particular neighborhood, e.g. /p/.')
         parser.add_argument(
@@ -109,5 +109,9 @@ class ReindexProjects(ScriptTask):
         return parser
 
 
+def get_parser():
+    return ReindexProjects.parser()
+
+
 if __name__ == '__main__':
     ReindexProjects.main()

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/Allura/allura/scripts/reindex_users.py
----------------------------------------------------------------------
diff --git a/Allura/allura/scripts/reindex_users.py b/Allura/allura/scripts/reindex_users.py
index 8a0762b..e2acd3b 100644
--- a/Allura/allura/scripts/reindex_users.py
+++ b/Allura/allura/scripts/reindex_users.py
@@ -73,7 +73,7 @@ class ReindexUsers(ScriptTask):
 
     @classmethod
     def parser(cls):
-        parser = argparse.ArgumentParser(description='Reindex all users')
+        parser = argparse.ArgumentParser(description='Reindex all users into Solr (for searching)')
         parser.add_argument('--dry-run', action='store_true', dest='dry_run',
                             default=False, help='Log names of projects that would be reindexed,
'
                             'but do not perform the actual reindex.')
@@ -85,5 +85,9 @@ class ReindexUsers(ScriptTask):
         return parser
 
 
+def get_parser():
+    return ReindexUsers.parser()
+
+
 if __name__ == '__main__':
     ReindexUsers.main()

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/Allura/docs/conf.py
----------------------------------------------------------------------
diff --git a/Allura/docs/conf.py b/Allura/docs/conf.py
index c201b9c..4c55afa 100644
--- a/Allura/docs/conf.py
+++ b/Allura/docs/conf.py
@@ -41,6 +41,7 @@ import os
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
               'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig']
+extensions += ['sphinxarg.ext']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -56,7 +57,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Apache Allura'
-copyright = '2012-2014 The Apache Software Foundation'
+copyright = '2012-2015 The Apache Software Foundation'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/Allura/docs/getting_started/administration.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/administration.rst b/Allura/docs/getting_started/administration.rst
index 4410f55..0b03728 100644
--- a/Allura/docs/getting_started/administration.rst
+++ b/Allura/docs/getting_started/administration.rst
@@ -19,13 +19,19 @@
 Administration
 **************
 
+.. contents::
+   :local:
+
 Commands, Scripts, and Tasks
-----------------------------
+============================
+
+Overview
+--------
 
-Allura has many `paster` commands and `paster` scripts that can be run from the
-server commandline to administrate Allura.  There are also tasks that can be
-run through the `taskd` system.  New tasks can be submitted via the web at
-/nf/admin/task_manager  Some paster commands and scripts have been set up
+Allura has many commands and scripts that can be run from the server commandline to
+administrate Allura.  There are also tasks that can be run through the `taskd` system
+in the background.  These tasks can be submitted via the web at
+http://MYSITE/nf/admin/task_manager  Some paster scripts have been set up
 so that they are runnable as tasks too, giving you the convenience of starting
 them through the web and letting `taskd` execute them, rather than from a server
 shell.
@@ -42,30 +48,116 @@ Commands can be discovered and run via the `paster` command when you
are in the
      paster create-neighborhood development.ini myneighborhood myuser ...
 
 
-Scripts are in the `scripts/` directory and run via `paster script`.  An extra
-`--` is required to separate script arguments from paster arguments.  Example::
+Scripts are in the `scripts/` directory and run slightly differently, via `paster script`.
 An extra
+:kbd:`--` is required to separate script arguments from paster arguments.  Example::
 
      paster script development.ini ../scripts/create-allura-sitemap.py -- --help
     ... help output ...
 
      paster script development.ini ../scripts/create-allura-sitemap.py -- -u 100
 
-TODO:   explain important scripts, commands
-
-Tasks can be run via the web interface at /nf/admin/task_manager  You must know
-the full task name, e.g. `allura.tasks.admin_tasks.install_app`  You can
+Tasks can be run via the web interface at http://MYSITE/nf/admin/task_manager  You must know
+the full task name, e.g. :code:`allura.tasks.admin_tasks.install_app`  You can
 optionally provide a username and project and app which will get set on the
 current context (`c`).  You should specify what args and kwargs will be passed
-as parameters to the task.  They are specified in JSON format on the form.
+as parameters to the task.  They are specified in JSON format on the form.  If you are
+running a script via this interface, the `args/kwargs` JSON should be like::
+
+    {
+        "args": ["--foo --bar baz"],
+        "kwargs": {}
+    }
 
 See the listing of :mod:`some available tasks <allura.tasks.admin_tasks>`.
 
-TODO: explain how to run scripttasks and commandtasks
+Available scripts and tasks are:
 
+disable_users.py
+----------------
 
-Client Scripts
+*Can be run as a background task using task name:* :code:`allura.scripts.disable_users.DisableUsers`
+
+.. argparse::
+    :module: allura.scripts.disable_users
+    :func: get_parser
+    :prog: paster script development.ini allura/scripts/disable_users.py --
+
+refreshrepo.py
 --------------
 
+*Can be run as a background task using task name:* :code:`allura.scripts.refreshrepo.RefreshRepo`
+
+.. argparse::
+    :module: allura.scripts.refreshrepo
+    :func: get_parser
+    :prog: paster script development.ini allura/scripts/refreshrepo.py --
+
+reindex_projects.py
+-------------------
+
+*Can be run as a background task using task name:* :code:`allura.scripts.reindex_projects.ReindexProjects`
+
+.. argparse::
+    :module: allura.scripts.reindex_projects
+    :func: get_parser
+    :prog: paster script development.ini allura/scripts/reindex_projects.py --
+
+reindex_users.py
+----------------
+
+*Can be run as a background task using task name:* :code:`allura.scripts.reindex_users.ReindexUsers`
+
+.. argparse::
+    :module: allura.scripts.reindex_users
+    :func: get_parser
+    :prog: paster script development.ini allura/scripts/reindex_users.py --
+
+create-allura-sitemap.py
+------------------------
+
+*Cannot currently be run as a background task.*
+
+.. argparse::
+    :file: ../../scripts/create-allura-sitemap.py
+    :func: parser
+    :prog: paster script development.ini ../scripts/create-allura-sitemap.py --
+
+publicize-neighborhood.py
+-------------------------
+
+*Cannot currently be run as a background task.*
+
+.. argparse::
+    :file: ../../scripts/publicize-neighborhood.py
+    :func: parser
+    :prog: paster script development.ini ../scripts/publicize-neighborhood.py --
+
+scrub-allura-data.py
+--------------------
+
+*Cannot currently be run as a background task.*
+
+.. argparse::
+    :file: ../../scripts/scrub-allura-data.py
+    :func: parser
+    :prog: paster script development.ini ../scripts/scrub-allura-data.py --
+
+teamforge-import.py
+-------------------
+
+*Cannot currently be run as a background task.*
+
+Extract data from a TeamForge site (via its web API), and import directly into Allura.  There
are some hard-coded
+and extra functions in this script, which should be removed or updated before being used
again.
+Requires running: :command:`pip install suds` first. ::
+
+    usage: paster script development.ini ../scripts/teamforge-import.py -- --help
+
+
+
+Client Scripts
+==============
+
 Allura includes some client scripts that use Allura APIs and do not have to be run
 from an Allura server.  They do require various python packages to be installed
 and possibly a local Allura codebase set up.
@@ -79,7 +171,7 @@ instance and uploads them to another Allura wiki instance.  It can be run
as:
 
 
 Site Notifications
-------------------
+==================
 
 Allura has support for site-wide notifications that appear below the site header,
 but there is currently no UI for managing them.  They can easily be inserted via
@@ -101,7 +193,7 @@ no notification will be shown.
 
 
 Using Projects and Tools
-------------------------
+========================
 
 We currently don't have any further documentation for basic operations of managing
 users, projects, and tools on Allura.  However, SourceForge has help docs that cover
@@ -110,6 +202,6 @@ that this documentation also covers some SourceForge features that are
not part
 
 
 Public API Documentation
-------------------------
+========================
 
 Allura's web api is currently documented at https://sourceforge.net/p/forge/documentation/Allura%20API/

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/requirements.txt
----------------------------------------------------------------------
diff --git a/requirements.txt b/requirements.txt
index fffb91d..eab35eb 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -79,4 +79,5 @@ WebTest==1.4.0
 testfixtures==3.0.0
 q==2.3
 WebError==0.10.3
+sphinx-argparse==0.1.15
 sphinx-rtd-theme==0.1.6

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/scripts/create-allura-sitemap.py
----------------------------------------------------------------------
diff --git a/scripts/create-allura-sitemap.py b/scripts/create-allura-sitemap.py
index f39b2a6..29220d1 100644
--- a/scripts/create-allura-sitemap.py
+++ b/scripts/create-allura-sitemap.py
@@ -142,7 +142,7 @@ def main(options):
             f.write(sitemap_index_content)
 
 
-def parse_options():
+def parser():
     import argparse
     class Validate(argparse.Action):
         def __call__(self, parser, namespace, value, option_string=None):
@@ -165,8 +165,11 @@ def parse_options():
     parser.add_argument('-n', '--neighborhood', dest='neighborhood',
                          help="URL prefix of excluded neighborhood(s)",
                          default=None, nargs='*')
+    return parser
+
+def parse_options():
+    return parser().parse_args()
 
-    return parser.parse_args()
 
 if __name__ == '__main__':
     sys.exit(main(parse_options()))

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/scripts/publicize-neighborhood.py
----------------------------------------------------------------------
diff --git a/scripts/publicize-neighborhood.py b/scripts/publicize-neighborhood.py
index c32d384..9cc6494 100644
--- a/scripts/publicize-neighborhood.py
+++ b/scripts/publicize-neighborhood.py
@@ -70,7 +70,7 @@ def main(options):
     return 0
 
 
-def parse_options():
+def parser():
     import argparse
     parser = argparse.ArgumentParser(
         description='Make all projects in a neighborhood public.')
@@ -81,7 +81,12 @@ def parse_options():
                         help='Run in test mode (no updates will be applied).')
     parser.add_argument('--log', dest='log_level', default='INFO',
                         help='Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).')
-    return parser.parse_args()
+    return parser
+
+
+def parse_options():
+    return parser().parse_args()
+
 
 if __name__ == '__main__':
     sys.exit(main(parse_options()))

http://git-wip-us.apache.org/repos/asf/allura/blob/053627a6/scripts/scrub-allura-data.py
----------------------------------------------------------------------
diff --git a/scripts/scrub-allura-data.py b/scripts/scrub-allura-data.py
index c0e0828..211cfdc 100644
--- a/scripts/scrub-allura-data.py
+++ b/scripts/scrub-allura-data.py
@@ -134,16 +134,23 @@ def main(options):
     return 0
 
 
-def parse_options():
+def parser():
     import argparse
     parser = argparse.ArgumentParser(
-        description='Removes private data from the Allura MongoDB.')
+        description='Removes private data from the Allura MongoDB.  DO NOT RUN THIS on your
main database.  '
+                    'This is intended to be used on a copy of your database, to prepare it
for sharing with others.'
+    )
     parser.add_argument('--dry-run', dest='dry_run', default=False,
                         action='store_true',
                         help='Run in test mode (no updates will be applied).')
     parser.add_argument('--log', dest='log_level', default='INFO',
                         help='Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).')
-    return parser.parse_args()
+    return parser
+
+
+def parse_options():
+    return parser().parse_args()
+
 
 if __name__ == '__main__':
     sys.exit(main(parse_options()))


Mime
View raw message