Re: OFP docs changes


Luis Gomez
 

So are you saying current version of sphinx in ODL Jenkins (3.0.4) is not compatible with the tabs plugin? do you have a jenkins rtd job failing for this reason? if so can you share the link?

BR/Luis

On Jul 11, 2020, at 1:16 AM, Dhiraj Sharma <dhiraj.8.sharma@...> wrote:

Hello all,

I just checked at https://stackoverflow.com/questions/56324234/does-anyone-know-how-to-use-sphinx-code-tabs compatibility was added for sphinx 2.0 versions and I am using sphinx 3.0.4 version.

I felt there may be the issue and i opened it on github at https://github.com/djungelorm/sphinx-tabs/issues/70

I will try with lower sphinx versions but are we ready to incorporate that in our documentation project? Will the Jenkins CI not fail even if I test it in lower versions?



Thank You
Dhiraj Sharma

On Sat, Jul 11, 2020 at 1:13 PM Dhiraj Sharma <dhiraj.8.sharma@...> wrote:
Hello all,
Sorry, I didn't select reply all earlier.Please check the below quoted strings.
Below this I have provided the issues I am facing now.

On Jul 10, 2020, at 1:14 AM, Dhiraj Sharma <dhiraj.8.sharma@...> wrote:

Hello all,
I have included the tabs but while building it locally, I ran into an error which I feel will persist even if I push and that is not correct way for me to push the errored work which consumes too much time.Please see the attachment the error was 'Unknown directive type "tabs". ' in operations.rst file and likewise in flow-examples.rst.

Also, if you see the documentation there are different headers which have different content types so for each header there will be 2 tabs "rfc 8040" and "normal one"
So, how do you plan to actually see it?
Moreover, are the XL/JSON payloads not the same?

My idea is to club content-types and other fields together and then add 2 tabs. Namely "XML" and "JSON"
Please check the example below:

**Headers:**

- **Content-type:** ``application/xml``

- **Accept:** ``application/xml``

- **Authentication:** ``admin:admin``

**URL:** ``/restconf/operational/network-topology:network-topology/topology/flow:1``

**RFC8040 URL:** ``/rests/data/network-topology:network-topology/topology=flow%3A1?content=nonconfig``

**Method:** GET

Similarly I added the same for JSON which is redundant.

I am planning to do it like shown below:

**Headers:**

- **Content-type:** ``application/xml``

- **Accept:** ``application/xml``

- **Content-type:** ``application/json``

- **Accept:** ``application/json``

- **Authentication:** ``admin:admin``

**URL:** ``/restconf/operational/network-topology:network-topology/topology/flow:1``

**RFC8040 URL:** ``/rests/data/network-topology:network-topology/topology=flow%3A1?content=nonconfig``

**Method:** GET

After this I have added 2 tabs as "XML", "JSON"


Thank You
Dhiraj Sharma

On Fri, Jul 10, 2020 at 10:53 AM Dhiraj Sharma <dhiraj.8.sharma@...> wrote:
Alright Sir,
I will share the updates in this thread.

On Jul 10, 2020 10:51, "Luis Gomez" <ecelgp@...> wrote:
cc-ing OFP list so they are aware what we are doing here.

Dhiraj, please keep OFP list in cc for any question or discussion related to OFP documentation.

BR/Luis

On Jul 8, 2020, at 1:02 PM, Luis Gomez <ecelgp@...> wrote:

See below:

On Jul 7, 2020, at 11:09 AM, Dhiraj Sharma <dhiraj.8.sharma@...> wrote:

Hello Sir,

Also, Can you tell me that Older Helium wiki, Full Release Sections which have repeated sentences needs to be updated?
Older Helium is at https://wiki-archive.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin:Main
Releases are at https://wiki-archive.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin:Releases
I think most of Older Helium documentation is obsolete, asa whatever was relevant was moved to docs so you can skip this section entirely.

For the release section, we currently have 2 relevant docs per release:

- release plan in TSC Jira
- release notes in docs project

So maybe you can just add links for these.

Also in general for getting started, user guides, dev guides, we want people to get the latest so you can use latest vs stable-magnesium in your links:

https://docs.opendaylight.org/projects/openflowplugin/en/stable-magnesium/index.html -> https://docs.opendaylight.org/projects/openflowplugin/en/latest/index.html




Please have a look at https://wiki.opendaylight.org/display/ODL/OpenFlow+Plugin updated wiki, the getting started and product backlog will be updated in one go as I have saved them in draft.
Rest all doubts have been carefully addressed correctly.
Thanks is looks good.


Thank You
Dhiraj Sharma
Moreover today , I even tried this below to check whether I was wrong in providing spaces in tabs like below.
..tabs::
..code-tab:: XML
table

..code-tab:: JSON
table2

Originally, I know it should be like
..tabs::

..code-tab:: XML

table

..code-tab:: JSON

table2

The error still persists so I have added the required recipients to tweak it.
Below I have attached the screenshots.

Screenshot (459): I used the right way to add tabs in the documentation.
Screenshot (460) : Tried version to get it working by removing spaces in between the tabs and code-tabs.
Screenshot (461) : Contains the tried version output of index.html built locally.Which didn't work as expected.

I had installed the latest pypi package which has sphin_tabs.tabs extension etc.I guess the lfdocs-conf need some changes where I am looking for a workaround.


Thank You
Dhiraj Sharma

On Fri, Jul 10, 2020 at 10:51 AM Luis Gomez <ecelgp@...> wrote:
cc-ing OFP list so they are aware what we are doing here.

Dhiraj, please keep OFP list in cc for any question or discussion related to OFP documentation.

BR/Luis

On Jul 8, 2020, at 1:02 PM, Luis Gomez <ecelgp@...> wrote:

See below:

On Jul 7, 2020, at 11:09 AM, Dhiraj Sharma <dhiraj.8.sharma@...> wrote:

Hello Sir,

Also, Can you tell me that Older Helium wiki, Full Release Sections which have repeated sentences needs to be updated?
Older Helium is at https://wiki-archive.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin:Main
Releases are at https://wiki-archive.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin:Releases
I think most of Older Helium documentation is obsolete, asa whatever was relevant was moved to docs so you can skip this section entirely.

For the release section, we currently have 2 relevant docs per release:

- release plan in TSC Jira
- release notes in docs project

So maybe you can just add links for these.

Also in general for getting started, user guides, dev guides, we want people to get the latest so you can use latest vs stable-magnesium in your links:

https://docs.opendaylight.org/projects/openflowplugin/en/stable-magnesium/index.html -> https://docs.opendaylight.org/projects/openflowplugin/en/latest/index.html




Please have a look at https://wiki.opendaylight.org/display/ODL/OpenFlow+Plugin updated wiki, the getting started and product backlog will be updated in one go as I have saved them in draft.
Rest all doubts have been carefully addressed correctly.
Thanks is looks good.


Thank You
Dhiraj Sharma

Join integration-dev@lists.opendaylight.org to automatically receive all group messages.