New consolidated Kytos-ng sphinx docs

[viniarck]

Problems

1. Kytos-ng still doesn't host all of the documentation rendered that Kytos used to provide (developer/admin guides and tutorials)
2. The lack of consolidated browsable docs makes it hard for newcomers to get started and to get a holistic understanding of Kytos-ng
3. The custom sphinx layout used by Kytos was beautifully designed, however, it's difficult to maintain and deploy for a team that doesn't have many front-end specialists at the moment

Linked issue: kytos-ng/documentation#5

Overview of the current existing docs

Old Kytos docs.kytos.io major docs projects:

a) Welcome doc landing page quick start docs.kytos.io/home/quick_start/
b) Developer guide docs.kytos.io/developer
c) Developer tutorials tutorials.kytos.io
d) Admin guide docs.kytos.io/admin/intro

Current kytos-ng.github.io docs:

• NApps OpenAPI rendered docs
• About
• License / CLA
• NApps general and miscellaneous information (DB collections/metadata/prefix cookies/MongoDB notes)
• Procedures
• Releases

New consolidated proposed docs

To solve problems 1-2:

• Consolidate all old Kytos major docs, items a) to d), into a single sphinx project on kytos repo (it used to be two, one on kytos repo and another on documentation for tutorials). This will improve searchability. Tutorials used to be in a different sphinx project mainly because of design/styling reasons that no longer is a benefit for our team.
• Host it on ReadTheDocs that's still being commonly used by sphinx docs projects. That way, once the docs is updated on kytos repo it'll be deployed on kytos-ng.readthedocs.org. Also, later on if a custom domain is bought we can also use it accordingly.
• Add a GitHub Action to lint sphinx related docs/ to make sure it's still buildable ensuring a continuous integration of the docs (ReadTheDocs will be able to follow our git tags accordingly).

To solve problem 3:

• Instead of using kytos_sphinx_theme we should stick to the default ReadTheDocs theme sphinx_rtd_theme, that's also visually nice and still provides search features, here's a preview of this default theme:

Finally:

• Also include and aggregate the blueprints rst files into the documentation in a dedicated sub section.
• Still maintain kytos-ng.github.io, but only maintain there these sections: "NApps OpenAPI rendered docs", "About" and "Releases". Anything else will be moved to kytos docs/ for consistency and browsability. In the "About" section will also explain that ReadTheDocs also exists. "Releases" could also be moved, but it would break links from document reports that our team have sent to NSF, so we won't move it.
• Update the contents for developer and admin guides, they are still outdated, Kytos-ng team only updated the tutorials so far based on our project priorities.
• On NApps readme.md page when explaining how to install a NApp we should replace it with a link to the developer guide. It's very likely that we'll need to move from python setup.py develop one day, and having a unified single place instead of on every NApp readme that will simplify (or when we support again "kytos napps install" if ever)

Feedback

Let me know if you have any feedback, suggestions or concerns or something else that you'd also like to cover.

This proposal is for version 2023.1.

[italovalcy]

Excellent proposal, @viniarck. I agree with the proposed changes and I also believe the RTD sounds like the best approach from now on.

My half bit of contribution would be the following points to take into consideration for this project:

• It would be nice if we have some place to document the Kytos-ng Events API, supported events, available objects, etc. Maybe moving the docs from the Napp's readme would cover this, just mentioned to be on the radar.
• What if we want to publish tutorials or general posts about Kytos? would the RTD page be the best place? Can we have a section for that ?
• on the original website (kytos-ng.github.io) it would be nice to have the link for RTD in the main/first page as well
• Let's have space for the kytos tests dashboard somewhere? (https://kytos-tests.amlight.net)

Also, not exactly about sphinx, but overall docs:

• should we create a kytos-ng page on wikipedia?
• should we create a kytos-ng page on LinkedIn? (other social medias as well?)

[viniarck]

@italovalcy great suggestions. I'll reply to each individually in new threads to facilitate followup.

[viniarck]

@italovalcy I've just answered your questions on each thread, thanks for your inputs and contribution.

[viniarck]

It would be nice if we have some place to document the Kytos-ng Events API, supported events, available objects, etc. Maybe moving the docs from the Napp's readme would cover this, just mentioned to be on the radar.

In the same way that we have rendered API docs, if we were to aggregate NApps Events dosc on kytos-ng.github.io that would improve searchability out of the gate (looking from a perspective of someone that's just first finding out about the project). The biggest drawback though is having to send two PRs (one for the Napp repo and another to kytos-ng.githubio) whenever NApp's KytosEvent is changed/added/removed. To avoid this drawback, maybe an intermediary step would be to move the the Events docs to a events.rst file, and then on kytos-ng.github.io have a section "Events" (similar to the API)? and then, only provide the links that would point to each events.rst file respectively? Maybe there's also a way to interpolate this during deployment. Let me know what you think or if you see a simpler or another alternative.

[viniarck]

Probably even the events.rst file might be left for another iteration though, since this would require dozens of PRs to structure and a bit more work, but certainly we need to keep on our radar (as you originally mentioned). Let me know if you'd agree, Italo.

[italovalcy]

Hi Vinicius, yes, sounds good to me. Let's move this to another iteration then.

[viniarck]

captured here #361

[viniarck]

What if we want to publish tutorials or general posts about Kytos? would the RTD page be the best place? Can we have a section for that ?

I think on RTD would fit very well considering that we've already have a Developer Guide and Admin Guide, we could categorize tutorial as a subsection of each guide, where general tutorials could be categorized under Admin Guide? In fact, on Admin Guide we have some general usages like how to using the console. Something like:

Developer Guide
  Tutorials
    Tutorial 1
Admin Guide
  Tutorials
    Tutorial 1

Here's a quick preview, I just confirmed that with three levels the HTML would still look good and not too cluterred:

Wdyt?

[italovalcy]

Excellent! Let's go for it.

[viniarck]

on the original website (kytos-ng.github.io) it would be nice to have the link for RTD in the main/first page as well

Sure thing. Let's add a link that's immediately evident to go to RTD.

[viniarck]

Captured here kytos-ng/kytos-ng.github.io#51

[viniarck]

Let's have space for the kytos tests dashboard somewhere? (https://kytos-tests.amlight.net)

Yes. This is tremendously valuable to have easily accessable. Considering that's being hosted at AmLight, maybe we can add a new section on kytos-ng.github.io explaining what we currently have in terms of quality assurance and what the dashboard represents? on RDT currently we have these major sections:

• Quick Start
  • How to use
• Admin Guide
• Developer Guide

I believe at this stage it would be easier to categorize on kytos-ng.github.io, since other than the quality badges we don't have much info about quality assurance in general yet. Let me know what you think or if you have another suggestion where to add it.

[italovalcy]

yes, I was thinking about having this page on the GitHub.io pages too

[viniarck]

Right. Mapped here kytos-ng/kytos-ng.github.io#52

[viniarck]

should we create a kytos-ng page on wikipedia?

Good idea. A short and concise paragraph would be great, and with links to our RTD and kytos-ng.github.io pages? wikipedia ranks high it could be helpful for project searchability

If later on, we end up buying a new domain for kytos-ng then we could also probably rank higher than the old kytos.io domain I believe, considering that currently kytos-ng string from github ranks higher:

[viniarck]

I mapped this as future_release on #357

[viniarck]

should we create a kytos-ng page on LinkedIn? (other social medias as well?)

That'd be great too. Who does typically maintain social media info at AmLight? Maybe this is something that we can ask Vassi what she thinks and if she could help out?

[viniarck]

I mapped this as future_release on #357

[viniarck]

Our team will use a custom domain, mapped a task here #360

[viniarck]

@italovalcy appreciated your idea, inputs and review on this discussion. Since the scope was sorted out, I'll close this discussion and map the rest of the tasks. Thanks.