[RA2] Convert to rst #2733

CsatariGergely · 2021-11-26T14:53:48Z

Removal of raw HTML elements
Removal of ToC
Removal of bogometers
Adding new line before and after lists
Harmonizing buleted lists to use *
Adding new line before and after headings

- Removal of raw HTML elements - Removal of ToC - Removal of bogometers - Adding new line before and after lists - Harmonizing buleted lists to use * - Adding new lie before and after headings Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

pgoyal01 · 2021-11-26T17:20:21Z

doc/ref_arch/kubernetes/README.md

@@ -36,17 +34,6 @@ This is Kubernetes based Reference Architecture (RA-2)
 | Chapter 07 | Lots of SME feedback |
 | Appendix B - Guidance For workload isolation (Multitenancy) with Kubernetes for application vendors | Still developing content |

-## Table of Contents


why delete these as these are easy traversal links for folks working in Github?

Fixed in 3abd355

pgoyal01 · 2021-11-26T17:28:11Z

These changes have broken all of the links. For example, in section Cloud Infrastructure Software Profile Capabilities, the table has links in the last column labeled "Specification Reference". The reference "ra2.ch.011" has the link "chapter04.md#42-kubernetes-node" but 4.2 no longer exists and thus the link takes you to the top of chapter 4.

karinesevilla

@CsatariGergely @pgoyal01 I agree with Pankaj. Without chapters and sections numbering, all the links are lost.
The documentation is difficult to read without the chapter's hierachy, there is a loss of guidance for github users.

gkunz · 2021-11-29T20:57:20Z

@karinesevilla @pgoyal01 the intention of the documentation update is to leverage automation for things like header numbering, tables of contents etc. We also have to be conscious that we have 1 input format (currently GitHub-flavored-markdown, in the future maybe rst) and 2 output formats: docx for the GSMA document and html on read-the-docs. The rendering on GitHub is an additional output, yet it is not the output format of the release. Unfortunately, the markdown flavor on GitHub, which is typically used by many on a daily basis, does not allow for much automation.

So, there is a tradeoff here between the ease of generating two release output formats and the development workflow on GitHub. Not sure if @CsatariGergely schedules another tech discuss meeting on this topic, but feel free to join and we'll discuss.

rgstori · 2021-11-29T22:19:13Z

doc/ref_arch/kubernetes/chapters/chapter02.md

@@ -38,30 +21,30 @@ To ensure alignment with the infrastructure profile catalogue, the following req
 - Those relating to Cloud Infrastructure Management
 - Those relating to Cloud Infrastructure Security

-### 2.2.1 Cloud Infrastructure Software Profile Capabilities
+### Cloud Infrastructure Software Profile Capabilities

 | Reference Model Section | Reference  | Description | Requirement for Basic Profile | Requirement for High-Performance Profile| Specification Reference |
 |---|---|---|---|---|---|
 | [4.1.2](../../../ref_model/chapters/chapter04.md#412-exposed-infrastructure-capabilities) | e.cap.001 | Max number of vCPU that can be assigned to a single Pod by the Cloud Infrastructure | At least 16  | At least 16  | [ra2.ch.011](chapter04.md#42-kubernetes-node)|


does changing the links like so fix them? I think we may fix the link with a regex if so

Suggested change

| [4.1.2](../../../ref_model/chapters/chapter04.md#412-exposed-infrastructure-capabilities) | e.cap.001 | Max number of vCPU that can be assigned to a single Pod by the Cloud Infrastructure | At least 16 | At least 16 | [ra2.ch.011](chapter04.md#42-kubernetes-node)|

| [4.1.2](../../../ref_model/chapters/chapter04.md#412-exposed-infrastructure-capabilities) | e.cap.001 | Max number of vCPU that can be assigned to a single Pod by the Cloud Infrastructure | At least 16 | At least 16 | [ra2.ch.011](chapter04.md#kubernetes-node)|

I've fixed all occurrences in 2a099bd and a8aa761

@karinesevilla @pgoyal01 the intention of the documentation update is to leverage automation for things like header numbering, tables of contents etc. We also have to be conscious that we have 1 input format (currently GitHub-flavored-markdown, in the future maybe rst) and 2 output formats: docx for the GSMA document and html on read-the-docs. The rendering on GitHub is an additional output, yet it is not the output format of the release. Unfortunately, the markdown flavor on GitHub, which is typically used by many on a daily basis, does not allow for much automation.

So, there is a tradeoff here between the ease of generating two release output formats and the development workflow on GitHub. Not sure if @CsatariGergely schedules another tech discuss meeting on this topic, but feel free to join and we'll discuss.

Sure, I've put it to next weeks meeting agenda.

karinesevilla · 2021-12-02T15:30:41Z

@gkunz @CsatariGergely I got it. I understod that there is no other alternative. For the reference links, we will have to remove the numbering manually to keep them active. I agree with markdown cleaning

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

CsatariGergely · 2021-12-03T11:50:41Z

I plan to do the whole rst conversion in this pr.

collivier · 2021-12-15T11:33:17Z

Ok then it's too early to review :)

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

pgoyal01 · 2021-12-27T18:01:42Z

doc/ref_arch/kubernetes/chapters/chapter01.rst

+Introduction
+------------
+
+The intention of this Reference Architecture is to develop a usable Kubernetes based platform for the Telecom operator community. The RA will be based on the standard Kubernetes platform where ever possible. This Reference Architecture for Kubernetes will describe the high level system components and their interactions, taking the `goals and requirements <../../../common/chapter00.md>`__ and mapping them to real-world Kubernetes (and related) components. This document needs to be sufficiently detailed and robust such that it can be used to guide the production deployment of Kubernetes within an operator, whilst being flexible enough to evolve with and remain aligned with the wider Kubernetes ecosystem outside of Telco.


all references to CNTT md documents should be changed to rst else changes made in rst files going forward wouldn't be refelcted in the links

At the moment we use a Sphinx plugin to blindly change all ".md"-s to ".html"-s in the relative links. Becouse of this all links are automagically working, however this is a bit of hacking of how rst works. I started to correct this and then realized that with :doc: directives the # anchors do not work, so the only way to refer correctly to chapters is to use :ref:-s what would require a manual annotating of all headings. Somehow I feel that at least for the beginning we should just keep using the relative-link-corrector for the existing links and start using proper rst linking for new text. Gradually we can start replacing all ".md" links with proper ones later. @pgoyal01 , @collivier , @gkunz , @karinesevilla what do you think?

@CsatariGergely That would be fine but if edit the referenced equivalent rst file then we would need to change references to the md version everywhere else we would be pointing to outdated content. That can be error-prone.

It may be worth dividing up the work amongst us -- assign Issues (the WSLs can do that) -- to go and add :ref:-s to each section header. We need to use a standard format and use only the text - no number. Wherever a reference uses a # should be changed to one with corresponding text.

Other Ideas?

Somehow I also have a feeling that manual labels are the most optimal on the long run, but I would like to get the conversion pr-s get merged before we start addressing them.

Cross-posting from another thread: In the RI1 and RI2 conversions, I have been using the :ref: directive in conjunction with the autosectionlabel extension to automatically create header references:

For intra-references using implicit header references, see https://github.com/cntt-n/CNTT/pull/2777/files#diff-774fcc11722dce98d0347ce9870d8c0959a06c61223d2ee4a1cc4516db7211b5R64

You have to use the autosectionlabel extention (see https://github.com/cntt-n/CNTT/pull/2777/files#diff-e59005d178179a798a25d32c0f18a66b77b4cd290462ac82d5594c23fb0ee0d6R15)

See also these options: https://github.com/cntt-n/CNTT/pull/2777/files#diff-e59005d178179a798a25d32c0f18a66b77b4cd290462ac82d5594c23fb0ee0d6R62 to avoid clashes of header references across files.

Thanks for the references. I've tried the approach, but for some reason it is not working for me. I would propose to merge the big rst conversion pr-s and fix smaller issues in different pr-s. Smaller issues so far are:

Consistent mechanism for referencing sections (preferably with :ref: and autosectionlabel)

Support for top level and document level builds

pgoyal01 · 2022-01-18T14:46:45Z

@walterkozlowski can you review, approve and merge?

rgstori · 2022-01-20T15:48:28Z

I don't own doc/ref_arch/README.md so @walterkozlowski has to merge this

- Conversion of abbreviations are undone - Creation of index.rst for RA1 and RA2 undone - Removal of README.md undone Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

CsatariGergely · 2022-01-26T00:54:58Z

I don't own doc/ref_arch/README.md so @walterkozlowski has to merge this

@rgstori I've undone the changes to doc/ref_arch/README.md. I will add them as a separate pr.

[RA2] Markdown corrections

a72d9ab

- Removal of raw HTML elements - Removal of ToC - Removal of bogometers - Adding new line before and after lists - Harmonizing buleted lists to use * - Adding new lie before and after headings Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

CsatariGergely requested review from collivier, gkunz, scottsteinbrueck, karinesevilla, bfcohen and a team November 26, 2021 14:53

CsatariGergely requested review from rgstori and walterkozlowski as code owners November 26, 2021 14:53

CsatariGergely added this to In Progress in old-RA2 via automation Nov 26, 2021

pgoyal01 reviewed Nov 26, 2021

View reviewed changes

karinesevilla reviewed Nov 29, 2021

View reviewed changes

rgstori reviewed Nov 29, 2021

View reviewed changes

karinesevilla approved these changes Dec 2, 2021

View reviewed changes

CsatariGergely added 3 commits December 3, 2021 13:38

[RA2]: Adding back main ToC and figure captions

3abd355

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

[RA2]: Removal of chapter numbers from links

2a099bd

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

[RA2]: Fixing bougus links

a8aa761

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

CsatariGergely marked this pull request as draft December 3, 2021 11:50

[RA2]: Convert to rst

8538b20

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

CsatariGergely changed the title ~~[RA2] Markdown corrections~~ [RA2] Convert to rst Dec 22, 2021

CsatariGergely marked this pull request as ready for review December 22, 2021 17:28

Merge branch 'master' into ra2-rst-md-corrections

987893c

Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

CsatariGergely requested review from rgstori, pgoyal01 and karinesevilla December 22, 2021 17:31

CsatariGergely requested a review from a team December 23, 2021 10:07

pgoyal01 reviewed Dec 27, 2021

View reviewed changes

This was referenced Dec 29, 2021

[RM]: convert to rst #2746

Merged

[RI1] Conversion to rst #2777

Merged

pgoyal01 approved these changes Dec 30, 2021

View reviewed changes

rgstori approved these changes Jan 4, 2022

View reviewed changes

[RA]: Undoing changes not strictly in RA2 scope

80cf955

- Conversion of abbreviations are undone - Creation of index.rst for RA1 and RA2 undone - Removal of README.md undone Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>

rgstori merged commit f0600be into anuket-project:master Jan 27, 2022

old-RA2 automation moved this from In Progress to Done Jan 27, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RA2] Convert to rst #2733

[RA2] Convert to rst #2733

CsatariGergely commented Nov 26, 2021 •

edited

Loading

pgoyal01 Nov 26, 2021

CsatariGergely Dec 3, 2021

pgoyal01 commented Nov 26, 2021

karinesevilla left a comment

gkunz commented Nov 29, 2021

rgstori Nov 29, 2021 •

edited

Loading

CsatariGergely Dec 3, 2021 •

edited

Loading

CsatariGergely Dec 3, 2021

karinesevilla commented Dec 2, 2021

CsatariGergely commented Dec 3, 2021

collivier commented Dec 15, 2021

pgoyal01 Dec 27, 2021

CsatariGergely Dec 29, 2021

pgoyal01 Dec 29, 2021

CsatariGergely Dec 29, 2021

gkunz Jan 4, 2022

CsatariGergely Jan 5, 2022

pgoyal01 commented Jan 18, 2022

rgstori commented Jan 20, 2022

CsatariGergely commented Jan 26, 2022

	\| [4.1.2](../../../ref_model/chapters/chapter04.md#412-exposed-infrastructure-capabilities) \| e.cap.001 \| Max number of vCPU that can be assigned to a single Pod by the Cloud Infrastructure \| At least 16 \| At least 16 \| [ra2.ch.011](chapter04.md#42-kubernetes-node)\|
	\| [4.1.2](../../../ref_model/chapters/chapter04.md#412-exposed-infrastructure-capabilities) \| e.cap.001 \| Max number of vCPU that can be assigned to a single Pod by the Cloud Infrastructure \| At least 16 \| At least 16 \| [ra2.ch.011](chapter04.md#kubernetes-node)\|

[RA2] Convert to rst #2733

[RA2] Convert to rst #2733

Conversation

CsatariGergely commented Nov 26, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pgoyal01 commented Nov 26, 2021

karinesevilla left a comment

Choose a reason for hiding this comment

gkunz commented Nov 29, 2021

rgstori Nov 29, 2021 • edited Loading

Choose a reason for hiding this comment

CsatariGergely Dec 3, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

karinesevilla commented Dec 2, 2021

CsatariGergely commented Dec 3, 2021

collivier commented Dec 15, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pgoyal01 commented Jan 18, 2022

rgstori commented Jan 20, 2022

CsatariGergely commented Jan 26, 2022

CsatariGergely commented Nov 26, 2021 •

edited

Loading

rgstori Nov 29, 2021 •

edited

Loading

CsatariGergely Dec 3, 2021 •

edited

Loading