diff --git a/_includes/shared_doc/how_to_contribute.md b/_includes/shared_doc/how_to_contribute.md index 70d7a0d..15af62a 100644 --- a/_includes/shared_doc/how_to_contribute.md +++ b/_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) - diff --git a/_layouts/default.html b/_layouts/default.html index 1becaf7..e0fb226 100644 --- a/_layouts/default.html +++ b/_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" %} +

How to contribute to user documentation

+ {% endif %} + {% if site.last_edit_timestamp or site.gh_edit_link %}
{% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %} diff --git a/assets/images/ontoportal/contribute-compare-forks.png b/assets/images/ontoportal/contribute-compare-forks.png new file mode 100644 index 0000000..512d704 Binary files /dev/null and b/assets/images/ontoportal/contribute-compare-forks.png differ diff --git a/assets/images/ontoportal/contribute-fork.png b/assets/images/ontoportal/contribute-fork.png new file mode 100644 index 0000000..9ebb5ab Binary files /dev/null and b/assets/images/ontoportal/contribute-fork.png differ diff --git a/assets/images/ontoportal/contribute-open-pr.png b/assets/images/ontoportal/contribute-open-pr.png new file mode 100644 index 0000000..c78d70b Binary files /dev/null and b/assets/images/ontoportal/contribute-open-pr.png differ diff --git a/assets/images/ontoportal/contribute-upload-commit.png b/assets/images/ontoportal/contribute-upload-commit.png new file mode 100644 index 0000000..756c10f Binary files /dev/null and b/assets/images/ontoportal/contribute-upload-commit.png differ diff --git a/assets/images/ontoportal/contribute-upload.png b/assets/images/ontoportal/contribute-upload.png new file mode 100644 index 0000000..b0d62de Binary files /dev/null and b/assets/images/ontoportal/contribute-upload.png differ diff --git a/assets/images/ontoportal/example_specific_file.png b/assets/images/ontoportal/example_specific_file.png index 745c428..33a8716 100644 Binary files a/assets/images/ontoportal/example_specific_file.png and b/assets/images/ontoportal/example_specific_file.png differ diff --git a/assets/images/ontoportal/file_head.png b/assets/images/ontoportal/file_head.png index d8acf3a..64cd3aa 100644 Binary files a/assets/images/ontoportal/file_head.png and b/assets/images/ontoportal/file_head.png differ diff --git a/assets/images/ontoportal/images_var_usage.png b/assets/images/ontoportal/images_var_usage.png index 1a04f8f..b8e2966 100644 Binary files a/assets/images/ontoportal/images_var_usage.png and b/assets/images/ontoportal/images_var_usage.png differ diff --git a/assets/images/ontoportal/shared_file_var_usage.png b/assets/images/ontoportal/shared_file_var_usage.png index eecde48..5725b45 100644 Binary files a/assets/images/ontoportal/shared_file_var_usage.png and b/assets/images/ontoportal/shared_file_var_usage.png differ diff --git a/docs/documentation-docs/how-to-contribute-doc.md b/docs/documentation-docs/how-to-contribute-doc.md index f44095e..fc94df7 100644 --- a/docs/documentation-docs/how-to-contribute-doc.md +++ b/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. \ No newline at end of file diff --git a/docs/users-guide-docs/contribute.md b/docs/users-guide-docs/contribute.md new file mode 100644 index 0000000..9191eed --- /dev/null +++ b/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%} \ No newline at end of file diff --git a/docs/users-guide-docs/index.md b/docs/users-guide-docs/index.md index 14af49a..6a258fa 100644 --- a/docs/users-guide-docs/index.md +++ b/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) -