Feature: Migrate the docs to the just-the-docs template

[syphax-bouazzouni]

Context

From our discussions

• OntoPortal documentation requirements and planning ontoportal-project#1

I extracted this action item " being able to search in the doc ", but to do that I needed to use a template (theme) that implement it. I did choose https://just-the-docs.github.io/just-the-docs/

Preview

See https://ontoportal-lirmm.github.io/documentation/administration

I migrated all the existent content and kept the same configuration data (status, description, order,....)

What's new

• Search feature

• Navigation bar

• Customize then template to show page status

• A documentation of how to use and configure the documentation (see https://ontoportal-lirmm.github.io/documentation/configuration)

[jonquet]

Looks good to me. Same docs that @graybeal did earlier but searchable and with a menu on the left. Awesome, exactly what was missing.
It does not address everything in pur documentation story, but it consolidates the choice of the github.io approach.
Ok to merge for me.
Waiting for the others opinion.

[arsarkar]

I recommend including a FAQ section for listing bug-fixing for commonly known issues for quick reference. e.g., the number of visits not being updated, the ontology page taking a long time to show the list of ontologies, the group cannot be updated for an ontology, etc. Over time, this FAQ section may become a troubleshooting guide and even a guided search may be built on top in the distant future.

[jonquet]

I recommend including a FAQ section for listing bug-fixing for commonly known issues for quick reference. e.g., the number of visits not being updated, the ontology page taking a long time to show the list of ontologies, the group cannot be updated for an ontology, etc. Over time, this FAQ section may become a troubleshooting guide and even a guided search may be built on top in the distant future.

@arsarkar OK. thanks for suggestion. Can you transform this into a feature request on the issues section.

[jonquet]

Good to me.

[xeniacs]

It looks good Syphax! Will the section about documentation configuration be visible to all who visit the page? If so, do you think this might be confusing to them?

[syphax-bouazzouni]

It looks good Syphax! Will the section about documentation configuration be visible to all who visit the page? If so, do you think this might be confusing to them?

Hi @xeniacs, thanks for your feedback. Yeah it will be visible and certainly it is confusing for visitors. I will surely remove/hide it in the future, but for now this PR is just about the technology behind the scene.

After I will let you @xeniacs , @jonquet , @graybeal, ... take the responsibilities of the editorial part (see discussion ontoportal/ontoportal-project#1)

And also can you please "approve this PR" if you agree with the change.

[graybeal]

There is a troubleshooting page (or two) and that/they may be repurposed into what you suggest. I think organizing them thematically may help people zero in on what they need.

[graybeal]

Caveats: I'm not capable of reviewing changes on 191 files, and I'm not technically proficient enough to understand what I'm looking at in this pull request. (Would be happy to have someone take the hour or three it would take to teach me....)

Nonetheless, I am approving the change, because (A) it adds an important feature, (B) any issues can be addressed in subsequent work if it is important, and (C) I trust Syphax's judgment about whether this is "better".

It is not clear to me that when the pull request is approved, the existing location of the docs https://ontoportal.github.io/administration/ will be serving this new material. I assume it will, but I think this is necessary because everything points to that location.

[syphax-bouazzouni]

Hi @graybeal , thanks for the approvement.

Caveats: I'm not capable of reviewing changes on 191 files, and I'm not technically proficient enough to understand what I'm looking at in this pull request. (Would be happy to have someone take the hour or three it would take to teach me....)

It's not really important to understand the technical behind, in this pull request you only need to check if it respond to our requirements for a centralized documentation for the alliance.

But yeah I have no problem "to take the hour or three hour" to explain it if needed,

Although what it is really important to document (in my opninoin) , is a "how to contribute to the documentation" page

It is not clear to me that when the pull request is approved, the existing location of the docs https://ontoportal.github.io/administration/ will be serving this new material. I assume it will, but I think this is necessary because everything points to that location.

In summary: "Yes"

In details:

Note: All the bellow sections discuss about the what's next and like it's not propose of this PR, I will transfer it after to our discussion about the doc and transform the actions to issues (if apporeved).

Yes, it will be the same, but we will have an editorial problem after.

That are:

• The current link https://ontoportal.github.io/administration will redirect to the documentation home (todo), see https://ontoportal-lirmm.github.io/documentation/
• The current docs that would be the future administration section at https://ontoportal.github.io/administration/administration.
• We will need surely to change the repository name from "administration" to "documentation" (to have a link like this https://ontoportal.github.io/documentation/administration for the existing docs)

In summary, the next actions after the merge (that I would propose) are:

• change the repository name from "administration" to "documentation"
• update the new documentation home (https://ontoportal-lirmm.github.io/documentation/ )
• link to the Code of Conduct (e.g., https://github.com/ncbo/bioportal-project/blob/master/contributing.md) in the home
• current link should redirect to the administration page through the documentation home
• add a how to contribute to the documentation (update https://github.com/ontoportal/administration/blob/master/docs/README.md)
• ...

[graybeal]

head to read this twice, but I think I got it with a few clarifications:

• create new documentation repo and host all sub-categories of documentation (like administration) within that
• Your second bullet should say The current docs that would be the future administration section would be at https://ontoportal.github.io/administration/administration.
• Your first bullet should say the current link should redirect to the administration page through (or under) the documentation home page (it shouldn't redirect to the top level, right?)

There is a page that describes in detail how to work with the documentation (I'm sure you are aware of that). But several caveats about that existing page:

• It will need some rewrites around the new organization/technology (not sure how many things need to change)
• (maybe your checklist#3) it does not include the Code of Conduct (e.g., https://github.com/ncbo/bioportal-project/blob/master/contributing.md) that we expect contributors to follow (the Home page you link to includes a Code of Conduct, but that's all copied from the Just the Docs documentation—that page needs updating (maybe your checklist#2))

Also, none of the 3 or so internal links that I've tested have worked. It may have to do with the way I used absolute or relative links, which IIRC were a little weird in the previous technology.

[syphax-bouazzouni]

create new documentation repo and host all sub-categories of documentation (like administration) within that

I think that there is no need to create a new repo, just changing the current one name would be enaugh

• Your second bullet should say The current docs that would be the future administration section would be at https://ontoportal.github.io/administration/administration.
• Your first bullet should say the current link should redirect to the administration page through (or under) the documentation home page (it shouldn't redirect to the top level, right?)
• (maybe your checklist#3) it does not include the Code of Conduct (e.g., https://github.com/ncbo/bioportal-project/blob/master/contributing.md) that we expect contributors to follow

I updated the bultes 👍

There is a page that describes in detail how to work with the documentation

Yes, this one: https://github.com/ontoportal/administration/blob/master/docs/README.md, we just need to update it (some infos will be depreacted, e.g there is no need of collections configuration) .

I think also we need to make less a detailed configuration documentation and more a guided tutorial of how to add/edit a page on the documentation. (it's just a proposition, but yes it is the subject of another discussion)

Also, none of the 3 or so internal links that I've tested have worked.

Fixed ontoportal-lirmm@7e204c1