Repository: ckan/ckan

Issue:
Update 'Common CKAN Administrator Tasks' docs for 2.0
A few things on this page are out of date, e.g. they refer to the old auth system: http://docs.ckan.org/en/latest/paster.html

Some new paster commands aren't documented.

Should the paster commands docs be pulled from docstrings by autodoc like the api and plugin interfaces docs are? Seems a better way to keep them up to date and not have to write the docs twice

Everything on this page seems to be paster commands, so should the page be renamed _CKAN Paster Commands_? The current title is a bit generic

This [Database Dumps](http://docs.ckan.org/en/latest/database-dumps.html) page is also just about a couple of paster commands, so maybe belongs on the same page with the rest of the paster commands now on its own page



Discussion:
@vitorbaptista Assigning this one to you. Can you try and make it pull the docs out of the source using autodoc? This is already done for the plugin interfaces and action API Ask me if you need any guidance. We're hoping to get these done by end of next week so we can release 2.0 in a couple of weeks


Resolving patch:
diff --git a/ckan/lib/cli.py b/ckan/lib/cli.py
--- a/ckan/lib/cli.py
+++ b/ckan/lib/cli.py
@@ -99,21 +99,21 @@ def _setup_app(self):
 class ManageDb(CkanCommand):
     '''Perform various tasks on the database.
 
-    db create # alias of db upgrade
-    db init # create and put in default data
+    db create                      - alias of db upgrade
+    db init                        - create and put in default data
     db clean
-    db upgrade [{version no.}] # Data migrate
-    db version # returns current version of data schema
-    db dump {file-path} # dump to a pg_dump file
-    db dump-rdf {dataset-name} {file-path}
-    db simple-dump-csv {file-path} # dump just datasets in CSV format
-    db simple-dump-json {file-path} # dump just datasets in JSON format
-    db user-dump-csv {file-path} # dump user information to a CSV file
-    db send-rdf {talis-store} {username} {password}
-    db load {file-path} # load a pg_dump from a file
-    db load-only {file-path} # load a pg_dump from a file but don\'t do
-                             # the schema upgrade or search indexing
-    db create-from-model # create database from the model (indexes not made)
+    db upgrade [version no.]       - Data migrate
+    db version                     - returns current version of data schema
+    db dump FILE_PATH              - dump to a pg_dump file
+    db dump-rdf DATASET_NAME FILE_PATH
+    db simple-dump-csv FILE_PATH   - dump just datasets in CSV format
+    db simple-dump-json FILE_PATH  - dump just datasets in JSON format
+    db user-dump-csv FILE_PATH     - dump user information to a CSV file
+    db send-rdf TALIS_STORE USERNAME PASSWORD
+    db load FILE_PATH              - load a pg_dump from a file
+    db load-only FILE_PATH         - load a pg_dump from a file but don\'t do
+                                     the schema upgrade or search indexing
+    db create-from-model           - create database from the model (indexes not made)
     '''
     summary = __doc__.split('\n')[0]
     usage = __doc__
@@ -312,10 +312,12 @@ class SearchIndexCommand(CkanCommand):
     '''Creates a search index for all datasets
 
     Usage:
-      search-index [-i] [-o] [-r] [-e] rebuild [dataset-name]     - reindex dataset-name if given, if not then rebuild full search index (all datasets)
-      search-index check                                     - checks for datasets not indexed
-      search-index show {dataset-name}                       - shows index of a dataset
-      search-index clear [dataset-name]                      - clears the search index for the provided dataset or for the whole ckan instance
+      search-index [-i] [-o] [-r] [-e] rebuild [dataset_name]  - reindex dataset_name if given, if not then rebuild
+                                                                 full search index (all datasets)
+      search-index check                                       - checks for datasets not indexed
+      search-index show DATASET_NAME                           - shows index of a dataset
+      search-index clear [dataset_name]                        - clears the search index for the provided dataset or
+                                                                 for the whole ckan instance
     '''
 
     summary = __doc__.split('\n')[0]
@@ -434,7 +436,7 @@ def command(self):
 
 
 class RDFExport(CkanCommand):
-    '''
+    '''Export active datasets as RDF
     This command dumps out all currently active datasets as RDF into the
     specified folder.
 
@@ -498,8 +500,8 @@ class Sysadmin(CkanCommand):
     Usage:
       sysadmin                      - lists sysadmins
       sysadmin list                 - lists sysadmins
-      sysadmin add <user-name>      - add a user as a sysadmin
-      sysadmin remove <user-name>   - removes user from sysadmins
+      sysadmin add USERNAME         - add a user as a sysadmin
+      sysadmin remove USERNAME      - removes user from sysadmins
     '''
 
     summary = __doc__.split('\n')[0]
@@ -579,16 +581,16 @@ class UserCmd(CkanCommand):
     Usage:
       user                            - lists users
       user list                       - lists users
-      user <user-name>                - shows user properties
-      user add <user-name> [<field>=<value>]
+      user USERNAME                   - shows user properties
+      user add USERNAME [FIELD1=VALUE1 FIELD2=VALUE2 ...]
                                       - add a user (prompts for password
                                         if not supplied).
                                         Field can be: apikey
                                                       password
                                                       email
-      user setpass <user-name>        - set user password (prompts)
-      user remove <user-name>         - removes user from users
-      user search <query>             - searches for a user name
+      user setpass USERNAME           - set user password (prompts)
+      user remove USERNAME            - removes user from users
+      user search QUERY               - searches for a user name
     '''
     summary = __doc__.split('\n')[0]
     usage = __doc__
@@ -735,11 +737,11 @@ class DatasetCmd(CkanCommand):
     '''Manage datasets
 
     Usage:
-      dataset <dataset-name/id>          - shows dataset properties
-      dataset show <dataset-name/id>     - shows dataset properties
+      dataset DATASET_NAME|ID            - shows dataset properties
+      dataset show DATASET_NAME|ID       - shows dataset properties
       dataset list                       - lists datasets
-      dataset delete <dataset-name/id>   - changes dataset state to 'deleted'
-      dataset purge <dataset-name/id>    - removes dataset from db entirely
+      dataset delete [DATASET_NAME|ID]   - changes dataset state to 'deleted'
+      dataset purge [DATASET_NAME|ID]    - removes dataset from db entirely
     '''
     summary = __doc__.split('\n')[0]
     usage = __doc__
@@ -816,12 +818,11 @@ class Celery(CkanCommand):
     '''Celery daemon
 
     Usage:
-        celeryd                 - run the celery daemon
-        celeryd run             - run the celery daemon
-        celeryd run concurrency - run the celery daemon with
-                                  argument 'concurrency'
-        celeryd view            - view all tasks in the queue
-        celeryd clean           - delete all tasks in the queue
+        celeryd <run>            - run the celery daemon
+        celeryd run concurrency  - run the celery daemon with
+                                   argument 'concurrency'
+        celeryd view             - view all tasks in the queue
+        celeryd clean            - delete all tasks in the queue
     '''
     min_args = 0
     max_args = 2
@@ -940,8 +941,8 @@ class Tracking(CkanCommand):
     '''Update tracking statistics
 
     Usage:
-      tracking update [start-date]        - update tracking stats
-      tracking export <file> [start-date] - export tracking stats to a csv file
+      tracking update [start_date]       - update tracking stats
+      tracking export FILE [start_date]  - export tracking stats to a csv file
     '''
 
     summary = __doc__.split('\n')[0]
@@ -1116,7 +1117,7 @@ def update_tracking(self, engine, summary_date):
         engine.execute(sql)
 
 class PluginInfo(CkanCommand):
-    ''' Provide info on installed plugins.
+    '''Provide info on installed plugins.
     '''
 
     summary = __doc__.split('\n')[0]
@@ -1220,8 +1221,8 @@ class CreateTestDataCommand(CkanCommand):
     create-test-data user         - create a user 'tester' with api key 'tester'
     create-test-data translations - annakarenina, warandpeace, and some test
                                     translations of terms
-    create-test-data vocabs  - annakerenina, warandpeace, and some test
-                               vocabularies
+    create-test-data vocabs       - annakerenina, warandpeace, and some test
+                                    vocabularies
 
     '''
     summary = __doc__.split('\n')[0]
@@ -1271,7 +1272,7 @@ class Profile(CkanCommand):
     by runsnakerun.
 
     Usage:
-       profile {url}
+       profile URL
 
     e.g. profile /data/search
 
@@ -1328,15 +1329,15 @@ def profile_url(url):
 
 
 class CreateColorSchemeCommand(CkanCommand):
-    ''' Create or remove a color scheme.
+    '''Create or remove a color scheme.
 
-    less will need to generate the css files after this has been run
+    After running this, you'll need to regenerate the css files. See paster's less command for details.
 
-    color              - creates a random color scheme
-    color clear        - clears any color scheme
-    color '<hex>'      - uses as base color eg '#ff00ff' must be quoted.
-    color <value>      - a float between 0.0 and 1.0 used as base hue
-    color <color name> - html color name used for base color eg lightblue
+    color               - creates a random color scheme
+    color clear         - clears any color scheme
+    color <'HEX'>       - uses as base color eg '#ff00ff' must be quoted.
+    color <VALUE>       - a float between 0.0 and 1.0 used as base hue
+    color <COLOR_NAME>  - html color name used for base color eg lightblue
     '''
 
     summary = __doc__.split('\n')[0]
@@ -1587,8 +1588,8 @@ def command(self):
 class TranslationsCommand(CkanCommand):
     '''Translation helper functions
 
-    trans js - generate the javascript translations
-    trans mangle - mangle the zh_TW translations for testing
+    trans js      - generate the javascript translations
+    trans mangle  - mangle the zh_TW translations for testing
     '''
 
     summary = __doc__.split('\n')[0]
@@ -1744,7 +1745,7 @@ class MinifyCommand(CkanCommand):
 
     Usage:
 
-        paster minify [--clean] <path>
+        paster minify [--clean] PATH
 
     for example:
 
@@ -1919,7 +1920,7 @@ def compile_less(self, root, less_bin, color):
 
 
 class FrontEndBuildCommand(CkanCommand):
-    ''' Creates and minifies css and JavaScript files
+    '''Creates and minifies css and JavaScript files
 
     Usage:
 
diff --git a/ckanext/datastore/commands.py b/ckanext/datastore/commands.py
--- a/ckanext/datastore/commands.py
+++ b/ckanext/datastore/commands.py
@@ -8,7 +8,7 @@
 
 class SetupDatastoreCommand(cli.CkanCommand):
     '''Perform commands to set up the datastore.
-    Make sure that the datastore urls are set properly before you run these commands.
+    Make sure that the datastore URLs are set properly before you run these commands.
 
     Usage::
 
@@ -16,9 +16,9 @@ class SetupDatastoreCommand(cli.CkanCommand):
 
     Where:
         SQL_SUPER_USER is the name of a postgres user with sufficient
-                         permissions to create new tables, users, and grant
-                         and revoke new permissions.  Typically, this would
-                         be the "postgres" user.
+                       permissions to create new tables, users, and grant
+                       and revoke new permissions.  Typically, this would
+                       be the "postgres" user.
 
     '''
     summary = __doc__.split('\n')[0]


Test patch: