Content for "Documentation" page

[vgeorge]

I suggest creating a document on Google Docs or Dropbox Paper to work on the content and, once finished, move it to the page.

Devseed will provide a section explaining how to find and download source data after we define the folder structure at S3.

Link: http://gep-explorer.surge.sh/documentation

The structure of sections can be changed.

cc @alekordESA @bpstewar

[akorkovelos]

@vgeorge can the documentation page be informed directly by rst (or md) files? If yes, can we use files already available here? It requires further editing and re-structure, of course..

[vgeorge]

@alekordESA Now the live website can fetch Markdown files from anywhere. Unfortunately we couldn't provide support for .rst, but Read the Docs has support for .md. As discussed, the implementation we could provide at the moment has some hard-coded parts and we need you to provide the general documentation structure as:

• Section titles
• Properties of pages to be included:
  • Name
  • URL on Explorer site
  • Link to markdown file

You can can check the link below for an example on how the Explorer generates the documentation page:

https://github.com/global-electrification-platform/explorer/blob/develop/app/assets/scripts/views/Docs.js#L12-L39

[akorkovelos]

@vgeorge GEP User Guide pages are updated now; rst file have been converted to md as you ll see here. Documentation shall include the following sections in order, each a separate md file:

• Overview
• GEP Explorer
• GEP Generator
• GEP Toolbox
• Interoperability
• Contact

[danielfdsilva]

@alekordESA we noticed that some of the pages contain html tags. We can enable html parsing but it is not recommended since it can introduce security problems. Do you think, you can remove it?

Also, image urls must be absolute otherwise the explorer won't be able to find them.

[akorkovelos]

@danielfdsilva what are the potential security problems from html tags and how can they affect the function of the Explorer? While I can remove some of them, other are necessary for better understanding of the content. (#153 also related to this right?)

Also, by absolute image url I understand that we need to provide something like https://github.com/global-electrification-platform/User_Guide/blob/master/user-manual/source/images/GEP_Explorer_1.jpg, right? If that is the case, we will need html parsing, or?

Would a simple solution for now be that we provide only the link to readthedocs in the Documentation page?

[vgeorge]

@alekordESA The About page is pure HTML, not parsed Markedown from a remote. If HTML is enabled the Explorer will be subject to script injection or might break if the source HTML is not formatted properly.

What if we change the "Documentation" navigation button to link directly to https://gep-user-guide.readthedocs.io? Would that work?

[danielfdsilva]

@alekordESA Allowing html could lead to the injection of malicious content. Although I don't think this will happen since the source repo is owned by you, someone may unwillingly forget to close a html tag, which could break the site. It is however very easy to enable html parsing if you want.

That being said, @vgeorge suggestion of linking to the docs repo would allow you to have a centralized place for the docs. Let me know what you prefer

[akorkovelos]

@danielfdsilva @vgeorge thank you for clarifying. Let us go then with @vgeorge suggestion, with the "Documentation" navigation button pointing directly to https://gep-user-guide.readthedocs.io. That ll work for now I guess.

[vgeorge]

Implemented.