revised documentation for contribution part

doc/source/configuration.rst

@@ -8,12 +8,13 @@ is recommended to read this part carefully.
 
 Since the swiss confederation's definition and the specification for the `OEREB Data Extract
 <https://www.cadastre.ch/content/cadastre-internet/de/manual-oereb/publication/instruction.download/
-cadastre-internet/de/documents/oereb-weisungen/Weisung-OEREB-Data-Extract-de.pdf>`__ is really tight,
-we had very narrow margins to develop the code. Using this pyramid plugin, you will get a running server
-providing the services to satisfy the federal specification. But to get this extract, you need to bind your
+cadastre-internet/de/documents/oereb-weisungen/Weisung-OEREB-Data-Extract-de.pdf>`__ is really precise,
+we had very narrow margins to develop the code. 
+Using this pyramid plugin, you will get a running server
+providing the services to satisfy the said federal specification. But to get this extract, you need to bind your
 data to this server. And this is basically what you need to configure.
 
-This section describes the different possibilities to adapt the application on various data structures or
+This section describes the different possibilities to adapt the application to work with various data structures or
 even custom data sources. If you are planning to implement such modifications, we suggest to check all possible
 solutions first, as the necessary effort can vary significantly depending on your specific needs.
 
@@ -22,31 +23,31 @@ solutions first, as the necessary effort can vary significantly depending on you
 Create the inital database setup
 --------------------------------
 
-Out of the box the pyramid_oereb server supports three different topic configuration in the database:
+Out of the box the pyramid_oereb server supports three different topic configurations in the database:
 
   - the **pyramid_oereb standard model**
   - the **interlis 2.3 OeREBKRM transfer model**
-  - the **oereblex topic model**
+  - the **OEREBlex topic model**
 
 Pyramid_oereb Standard Model
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This schema and table structure is based on the initial topic structure used in the pyramid_oereb
 v1.x versions. It's mainly used for cantonal topics which are not (yet) stored in the interlis 2.3 OeREBKRM-
-Transfer structure and for cantons that do not use OeREB-Lex to manage the legal documents.
+Transfer structure and by cantons that do not use OeREB-Lex to manage the legal documents.
 
 Interlis 2.3 OeREBKRM Transfer Model
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 All the federal data sets are provided in this data structure. So this is the schema and table model you
 want to use for all the federal topics unless you want to remap the data to a specific database structure.
-If your cantonal data is also stored according to this model, then you might want to use this structure 
+If your cantonal data is also stored based on this model, then you probably want to use this structure 
 for all topics to homogenize your database content.
 The `Ili2pg Oereb Data Import Manual <https://github.com/openoereb/ili2pg_oereb_data_import_manual>`__
 explains how to use ili2pg tool to create the corresponding schema and how to import the XML data.
 
 
-OeREBlex Topic Model
+OEREBlex Topic Model
 ^^^^^^^^^^^^^^^^^^^^
 
 This third model is usefull if you maintain your legal documents using the OEREBlex application and you
@@ -59,7 +60,7 @@ Add additional standard topics
 ------------------------------
 
 If you like to add one or more additional topics based on the *pyramid_oereb standard* database structure
-you can use the internal command below to create an SQL script to establish the topic schema.
+you can use the internal command below creating an SQL script to establish the topic schema.
 
 But before creating any new topic structure you have to add its configuration. Open the configuration file
 (pyramid_oereb.yml) and copy the section from one of the existing **standard** topics which usually 
@@ -118,8 +119,8 @@ looks like this:
           transfer_code: Hinweis
           extract_code: Hint
 
-Apply the necessary modifications for the new topic. This should at least be the the schema name, code, geometry type
-and of course the models property within the source parameters:
+Apply the necessary modifications/replacements for the new topic. This should at least be the the schema name, 
+code, geometry type and of course the models property within the source parameters:
 Make sure that this source class is `pyramid_oereb.contrib.data_sources.*standard*.sources.plr.DatabaseSource`
 and not interlis_2_3. - The same goes for the model_factory and the get_symbol element. It should be set to
 *standard*.
@@ -135,10 +136,10 @@ Once the the configuration set, run the following command:
     --sql-file=<PATH_AND_SQL_SCRIPTNAME> -w [to over-write existing sql instead of append]
 
 The first parameter ``-c or --configuration=YAML`` is the path to your YAML configuration file. 
-By default it's pyramid_oereb.yml
+By default it's *pyramid_oereb.yml*
 
 The second optional parameter ``-s or --section=SECTION`` allows you to specify the section containing
-the configuration part to use. Default is pyramid_oereb.
+the configuration part to use. Default is *pyramid_oereb*.
 
 The parameter ``-T or --tables-only`` skips the schema creation and creates only the tables.
 
@@ -150,15 +151,16 @@ If your yaml file uses the c2ctemplate style (starting with vars) you need to ad
 
 The option ``-w or --over-write`` allows you to overwrite an existing sql file. Default is append.
 
-Now you have set up an empty additional topic and you can continued with deploying your data into it.
+Now you have set up an empty additional topic in your database and you can proceed with deploying 
+your data into it.
 
 Add additional interlis topics
 ------------------------------
 
 Follow the `Ili2pg Oereb Data Import Manual <https://github.com/openoereb/ili2pg_oereb_data_import_manual>`__
-to create a new topic schema based on the OeREBKRM Transfer model and how to import the XML data.
+to create a new topic schema based on the OeREBKRM Transfer model and about how to import the XML data.
 
-Once the schema is created do not forget to add the corresponding topic configuration in the pyramid_oereb.yml
+Once the schema is created do not forget to add the corresponding topic configuration in the *pyramid_oereb.yml*
 
 .. code-block:: yaml
 
@@ -219,28 +221,33 @@ Here the source class is `pyramid_oereb.contrib.data_sources.*interlis_2_3*.sour
 and not standard. - The same goes for the model_factory and the get_symbol element. It should be set to
 *interlis_2_3*.
 
-Also set the language of the data and if it's a federal (true) or cantonal topic (false). You also want to
+Also define the language of the data and if it's a federal (true) or cantonal topic (false). You also want to
 define that it is *NOT* the standard structure (false) and what lookup codes are used for the law_status 
 and document types.
 
-Add an oereblex topic
+Add an OEREBLex Topic
 ---------------------
 
-If you want to use oereblex for a topic, you can proceed as described in the previous section,
+If you want to use the OEREBlex structure for a topic, you can proceed as described in the previous section,
 but using a different script to generate the required models.
 
 .. code-block:: shell
 
    create_oereblex_tables -c <YOUR_NEW_TOPIC_CODE> -g <GEOMETRY_TYPE> -p <TARGET_PATH> -k TRUE
 
+For all topics
+~~~~~~~~~~~~~~
+
+Do not forget to add the availability information in the *pyramid_oereb_main.availability* table to activate (or not)
+the topic for a municipality.
 
 .. _configuration-adapt-models:
 
 Adapt existing models
 ---------------------
 
 Another option to modify the standard configuration, is to adapt the existing models to fit another database
-structure. This method is recommended if you are using an existing database supported by GeoAlchemy 2 and
+structure. This method is recommended if you are using an existing database supported by GeoAlchemy2 and
 already containing all the necessary data but in a different structure. In this case you should check, if it
 is possible to transform the data by extending the existing models with a mapping to fit your structure.