Added instructions on the user documentation contribution guide and m…

…oved the guide page link to the footer (#72)

* Added instructions on the user documentation contribution guide and moved the guide page link to the footer

* Fixed oversight when moving contribution guide to a separate page

_includes/shared_doc/how_to_contribute.md

@@ -1,15 +1,44 @@
-## How to contribute
+## How to contribute to user documentation
+In the following sections, you will find straightforward description of how to contribute to this user guide, edit shared files between the portals in the alliance, and add or edit specific content for each portal.
+If you don't know how to use Git to edit this documentation, please use the following guide: [How to contribute on github](../../documentation/docs/documentation-docs/how-to-contribute-doc/)
+
+## Files structure
+The files are structured as follows:
+
+- Shared content across all portals is located in the folder: `_includes/shared_doc`
+- Each portal has its own folder named with the name of the portal in: `docs/users-guide-docs/documentation`
+- Figures can be found in the folder: `assets/images/figures/ontoportal/PortalName` (create a new folder if needed)
+- From each portal's specific file, we can include the shared documentation to add to it or incorporate specific content.
+
+![files structure]({{site.baseimgs}}/files_structure.png)
+
+### Front matters
+- In the very top of each documentation page you need to specify these front matters to make your section appears in tables of content and the side navigation table:
+![files head]({{site.baseimgs}}/file_head.png)
+    - **title**: the title of the page. Documentation pages sharing the same title with other portals should be identified as specific to your portal by adding a space followed by @ and the name of your portal: `@PortalName`. The full title including the identifier will then be used to designate it at the parent when writing children pages: `parent: My title @PortalName`.
+    - **summary**: a brief description of the page. It will appear in the table of content of the parent page, if there's any.
+    - **layout**: the page layout. Leave it to default.
+    - **parent**: the parent page. Used to define a hierarchy.
+    - **grand_parent**: if the page is deeper in the hierarchy and Users guide is not the parent, then it Users guide becomes the grand_parent.
+    - **permalink**: defines the end part of the URL of this page. Append the name of your portal at the end of the URL, as shown in the example.
+    - **nav_order**: defines the index of the page in the table of content on the left side.
+- There are additional front matters you can use that are defined portal-wide (found in ` _config.yml`), but can also be redefined in the header of each page:
+    - **display_ontoportal_tabs**: if set to false, it will not show other OntoPortal tabs at the bottom of the page
+    - **atom**: define the core naming used for semantic resources (semantic artefact, ontology, etc...)
+    - **atoms**: same than previously, but in plural
+    - **portal**: the name of the portal
 
 ### How to add a new shared section?
 
 1. Create a new file with the extension `.md` within this path: `shared_doc/chapter_name/section_name/sub_section_name.md`
 2. Populate it with the desired content.
+3. Instead of writing "ontology" or "semantic artefact", write `{% raw %}{{ page.atom }}{% endraw %}` instead (or `{% raw %}{{ page.atoms }}{% endraw %}` for the plural form). Each portal can then decide which name they prefer to use.
 
 ### How to use this shared content for different portals?
 
 1. Create a new file with the extension `.md` within this path: `docs/users-guide-docs/documentation/portal_name/chapter_name/section_name.md`
 
-2. Inside this file, use this command: `include shared_doc/chapter_name/section_name/sub_section_name.md` to include the desired file.
+2. Inside this file, use this command: `{% raw %}{% include shared_doc/chapter_name/section_name/sub_section_name.md %}{% endraw %}` to include the desired file.
 
 3. To include multiple files, simply repeat the same command, specifying the correct file names each time.
 
@@ -24,38 +53,12 @@
 
 1. Inside the shared file, instead of writing the name of the portal, for example AgroPortal, you replace it by the variable `page.portal`
 ![shared_file_var_usage]({{site.baseimgs}}/shared_file_var_usage.png)
-2. When you include this file, you need to pass the value of the portal variable like this:  `include shared_doc/chapter_name/section_name/sub_section_name.md portal="AgroPortal"`
+2. When you include this file in a specific portal's doc, the portal name is automatically passed to it. The portal name is stored in the variable `page.portal` and can be found at the end of the `_config.yml`.
 
 ### How can screenshots or figures, which vary between portals, be incorporated into the shared files?
 
 1. Put the figure in this path: `assets/images/ontoportal/figures/portal_name/figure_name.png`
-2. Use this command
+2. Include the figure in the documentation with this command: `{% raw %}[MyFigureTitle]({{site.figures_link}}{{page.portal}}/MyFigure.png){% endraw %}`
 ![images_var_usage]({{site.baseimgs}}/images_var_usage.png)
-3. When you include this file in a specific portal's doc, you need to pass the value of the portal variable like this:  `include shared_doc/chapter_name/section_name/sub_section_name.md portal="AgroPortal"`
-
-### Important notes
-- In the very top of the portal's file, you need to specify these params to make your section appears in the Table of contents and the side nav:
-![files head]({{site.baseimgs}}/file_head.png)
-
-- Also in these files, you need always to add this command in before including or writing any content to include the navigation (portal's logos)
-`include documentation_nav.html portal="AgroPortal"`
-
-- To put a command inside a `.md` file you need to put it inside {% HERE %}
-
-- To use a variable inside your text, you need to put it inside { include.VAR_NAME }
-
-- Documentation pages sharing the same title with other portals should be identified as specific to your portal by adding a space followed by @ and the name of your portal: ` @PortalName`. The full title including the identifier will then be used to designate it at the parent when writing children pages: `parent: My title @PortalName`.
-
-[How to contribute on github](../../documentation/docs/documentation-docs/how-to-contribute-doc/)
-
-## Files structure
-The files are structured as follows:
-
-- Shared content across all portals is located in the folder: `_includes/shared_doc`
-- Each portal has its own folder named with the name of the portal in: `docs/users-guide-docs/documentation`
-- From each portal's specific file, we can include the shared documentation to add to it or incorporate specific content.
-
-![files structure]({{site.baseimgs}}/files_structure.png)
-
 
 

_layouts/default.html

@@ -208,6 +208,10 @@
 
             {{ footer_custom }}
 
+            {% if page.title == "Users guide" or page.parent == "Users guide" or page.grand_parent == "Users guide" %}
+              <p class="text-small"><a href="/documentation/user_guide/contribute">How to contribute to user documentation</a></p>
+            {% endif %}
+
             {% if site.last_edit_timestamp or site.gh_edit_link %}
               <div class="d-flex mt-2">
                 {% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %}

docs/documentation-docs/how-to-contribute-doc.md

@@ -44,3 +44,27 @@ At the bottom of each page, you will find a link that will take you to the corre
 ### Make your change and submit a commit
 ![image](https://user-images.githubusercontent.com/29259906/207832629-ba36a90d-376e-4705-ab10-b3513eec0660.png)
 
+## How to add images
+
+### Fork the project
+You can't upload a file directly to the repository. Instead, you need to fork the project:
+![image]({{site.baseimgs}}/contribute-fork.png)
+If you already forked the project, you can click the "Sync fork" button in your repository to make sure it is up to date with the current state of the documentation.
+
+### Upload an image, commit and open a pull request
+Navigate to `assets/images/ontoportal` (or `assets/images/ontoportal/figures/PortalName` for user documentation figures) and click "Add file":
+![image]({{site.baseimgs}}/contribute-upload.png)
+
+
+Drag and drop or select your file and then commit into a new branch:
+![image]({{site.baseimgs}}/contribute-upload-commit.png)
+
+
+Open a pull request onto the original repository. Click "compare across forks" to access it:
+![image]({{site.baseimgs}}/contribute-compare-forks.png)
+
+
+Select `base repository: ontoportal/documentation` and `base: master`
+You can now create the pull request:
+![image]({{site.baseimgs}}/contribute-open-pr.png)
+Note: you can also add and modify documentation pages in the new branch before creating a pull request.

docs/users-guide-docs/contribute.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Contribute
+permalink: /user_guide/contribute
+parent: Users guide
+nav_exclude: true
+---
+{% include shared_doc/how_to_contribute.md%}

docs/users-guide-docs/index.md

@@ -12,13 +12,8 @@ permalink: /user_guide
 Welcome to the official OntoPortal User Guide for each portal within the OntoPortal alliance. Please select a chapter or section from the menu to get started.
 
 
-In the following sections, you will find straightforward description of how to contribute to this user guide, edit shared files between the portals in the alliance, and add or edit specific content for each portal.
-
-{% include shared_doc/how_to_contribute.md%}
-
 links:
 - NCBO docs: [NCBO wiki](https://www.bioontology.org/wiki/Main_Page) and  [Bioportal Help](https://www.bioontology.org/wiki/BioPortal_Help)
 - [Our Scientific papers](https://github.com/ontoportal/literature) 
 - [API documentation](http://data.agroportal.lirmm.fr/documentation) 
 - [Ecoportal docs](https://github.com/lifewatch-eric/documentation/wiki/EcoTools) 
-