You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by je...@apache.org on 2015/07/13 12:44:11 UTC
[07/29] allura git commit: [#6373] document common admin scripts
[#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/acd50e8d
Tree: http://git-wip-us.apache.org/repos/asf/allura/tree/acd50e8d
Diff: http://git-wip-us.apache.org/repos/asf/allura/diff/acd50e8d
Branch: refs/heads/ib/7685
Commit: acd50e8d8e1cb00a5413f6a9caa227b401ff12b4
Parents: 93a1ecc
Author: Dave Brondsema <da...@brondsema.net>
Authored: Wed Jul 1 12:49:45 2015 -0400
Committer: Dave Brondsema <da...@brondsema.net>
Committed: Wed Jul 8 17:00:48 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/acd50e8d/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/acd50e8d/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/acd50e8d/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/acd50e8d/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/acd50e8d/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/acd50e8d/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/acd50e8d/requirements.txt
----------------------------------------------------------------------
diff --git a/requirements.txt b/requirements.txt
index fffb91d..80eda02 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
+-e git://github.com/brondsem/sphinx-argparse.git#egg=sphinx-argparse # pending merge requests
sphinx-rtd-theme==0.1.6
http://git-wip-us.apache.org/repos/asf/allura/blob/acd50e8d/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/acd50e8d/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/acd50e8d/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()))