Reorganize documentation and fix citation.

doc/source/_extensions/latest_citation.py

@@ -18,30 +18,29 @@ def get_latest_zenodo_citation(self):
         response = requests.get(url)
         data = response.json()
         latest_record = data['hits']['hits'][0]
-        authors = ' and '.join(
-            [author['name'] for author in latest_record['metadata']['creators']]
-        )
-        title = latest_record['metadata']['title']
+        authors = [author['name'] for author in latest_record['metadata']['creators']]
+        combine_chars = [', ']*(len(authors)-2) + [', and ']
+        author_str = authors[0]
+        for author, combine_char in zip(authors[1::], combine_chars):
+            author_str += combine_char + author
+        title = latest_record['metadata']['title'].split(': ')[0]
         version = latest_record['metadata']['version']
         doi = latest_record['metadata']['doi']
         year = latest_record['metadata']['publication_date'][:4]
         month = latest_record['metadata']['publication_date'][5:7]
         publisher = 'Zenodo'
-        url = f'https://doi.org/{doi}'
 
         # Standard citation
-        citation_text = f'{authors}. ({year}). {title}. Zenodo. DOI {doi}'
+        citation_text = f'{author_str} ({year}) {title}. DOI:{doi}'
 
         # BibTeX citation
-        bibtex_text = f"""@software{{{authors.replace(" ", "_").lower()}_{year}_{doi.split('.')[-1]},
-  author       = {{{authors}}},
+        bibtex_text = f"""@software{{{author_str.replace(" ", "_").replace(",", "").replace("_and_", "_").lower()}_{year}_{doi.split('.')[-1]},
+  author       = {{{" and ".join(authors)}}},
   title        = {{{title}}},
-  month        = {month},
   year         = {year},
   publisher    = {{{publisher}}},
   version      = {{{version}}},
   doi          = {{{doi}}},
-  url          = {{{url}}}
 }}"""
 
         return citation_text, bibtex_text

doc/source/examples/index.rst

@@ -2,9 +2,9 @@
 
 .. _examples:
 
-*************
-Example Index
-*************
+********
+Examples
+********
 
 Pelicun examples are listed in the following index.
 

doc/source/index.rst

@@ -15,44 +15,41 @@ Community-driven, easy to use and extend, it serves as an integrated multi-hazar
 Utilized in both academia and industry, it supports cutting-edge natural hazards engineering research while helping spread the adoption of performance-based engineering in practical applications.
 
 .. toctree::
-   :caption: User Guide
+   :caption: About
    :maxdepth: 1
    :numbered: 4
 
-   user_guide/install
-   user_guide/pelicun_framework
-   user_guide/feature_overview
-   user_guide/damage_and_loss_library
-   user_guide/bug_reports_and_feature_requests
-   user_guide/resources_for_new_python_users
-
-.. toctree::
-   :caption: Examples
-   :maxdepth: 1
-
-   examples/index
+   about/license.rst
+   about/cite.rst
+   about/acknowledgments.rst
+   release_notes/index.rst
 
 .. toctree::
-   :caption: Developer Guide
+   :caption: The Pelicun Framework
    :maxdepth: 1
    :numbered: 4
 
-   developer_guide/getting_started
-   developer_guide/development_environment
-   developer_guide/code_quality
-   developer_guide/internals
+   pelicun_framework/pelicun_framework.rst
 
 .. toctree::
-   :caption: API Reference
+   :caption: User Guide
    :maxdepth: 1
+   :numbered: 4
 
+   user_guide/install.rst
+   user_guide/feature_overview.rst
+   user_guide/damage_and_loss_library.rst
+   user_guide/bug_reports_and_feature_requests.rst
+   user_guide/resources_for_new_python_users.rst
+   examples/index.rst
    api_reference/index.rst
 
 .. toctree::
-   :caption: Other
+   :caption: Developer Guide
    :maxdepth: 1
+   :numbered: 4
 
-   release_notes/index.rst
-   other/license
-   other/cite
-   other/acknowledgments
+   developer_guide/getting_started.rst
+   developer_guide/development_environment.rst
+   developer_guide/code_quality.rst
+   developer_guide/internals.rst

doc/source/user_guide/pelicun_framework.rst → doc/source/pelicun_framework/pelicun_framework.rst

@@ -1,8 +1,5 @@
 .. _pelicun_framework:
 
-The pelicun framework
----------------------
-
 .. admonition:: Coming soon.
 
    This section is still under construction.
@@ -193,3 +190,14 @@ Collapses and their consequences are also handled by the damage and the loss mod
 Similarly to the performance model, the randomness in damage and losses is handled with a few high-dimensional random variables. This allows researchers to experiment with various correlation structures between damages of components, and consequences of those damages. Among the consequences, the repair costs and times and the number of injuries of various severities are also linked; allowing, for example, to consider that repairs that cost more than expected will also take longer time to finish.
 
 Once the damage and loss models are assembled, the previously sampled EDPs are used to evaluate the Damage Measures (Fig. 3). These DMs identify the Damage State of each Component Group in the structure. This information is used by the loss simulation to generate the Decision Variables. The final step of the calculation in pelicun is to aggregate results into a Damage and Loss (DL) file that provides a concise overview of the damage and losses. All intermediate data generated during the calculation (i.e., EDPs, DMs, DVs) are also saved in CSV files.
+
+Assessment
+..........
+
+.. admonition:: Coming soon.
+
+   This section is still under construction.
+
+   Section objectives:
+
+   - Discuss assessment objects.