[RFC] Documents under RedfishPkg


Abner Chang
 

Hi edk2 Stewards,
Is that ok to put some EDK2 Redfish port guide or design block diagrams in a folder under RedfishPkg? e.g. RedfishPkg/Documents?
Any practices we have on the current edk2 repo?
Thanks
Abner


Laszlo Ersek
 

On 03/26/21 16:42, Abner Chang wrote:
Hi edk2 Stewards,
Is that ok to put some EDK2 Redfish port guide or design block diagrams in a folder under RedfishPkg? e.g. RedfishPkg/Documents?
Any practices we have on the current edk2 repo?
If you can add the documents in some text-based representation (markup
or plaintext), where "reviewing patches" will make sense in the future,
then I welcome adding the documentation under RedfishPkg.

(If you have diagrams, I think SVG might be good for those.)

Other packages have introduced porting and other accompanying
documentation in the wiki, but I find that inferior. I don't like it
when documentation lives in a separate repository from the code that it
documents.

Thanks
Laszlo


Michael D Kinney
 

Hi Abner,

PlantUML is a way to embed some graphics in GitHub markdown text. Avoids checking in SVG or BMP or PNG binaries.

https://plantuml.com/

https://plantuml.com/en/guide


Here is an example of using PlatUML from a Wiki page with the PlantUML source text file also checked in.

https://github.com/tianocore-docs/edk2-TemplateSpecification/wiki/TianoCore-Documents-GitBook-Overview#introduction

GitHub Markdown source line that uses PlantUML server to convert PlantUML source to a SVG when the page is viewed.

![GitBookOverview](http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/wiki/tianocore-docs/edk2-TemplateSpecification/plantuml/GitBookOverview.puml)

PlantUML source file

https://raw.githubusercontent.com/wiki/tianocore-docs/edk2-TemplateSpecification/plantuml/GitBookOverview.puml


Mike

-----Original Message-----
From: rfc@edk2.groups.io <rfc@edk2.groups.io> On Behalf Of Laszlo Ersek
Sent: Tuesday, April 6, 2021 7:06 AM
To: rfc@edk2.groups.io; abner.chang@hpe.com
Subject: Re: [edk2-rfc] [RFC] Documents under RedfishPkg

On 03/26/21 16:42, Abner Chang wrote:
Hi edk2 Stewards,
Is that ok to put some EDK2 Redfish port guide or design block diagrams in a folder under RedfishPkg? e.g.
RedfishPkg/Documents?
Any practices we have on the current edk2 repo?
If you can add the documents in some text-based representation (markup
or plaintext), where "reviewing patches" will make sense in the future,
then I welcome adding the documentation under RedfishPkg.

(If you have diagrams, I think SVG might be good for those.)

Other packages have introduced porting and other accompanying
documentation in the wiki, but I find that inferior. I don't like it
when documentation lives in a separate repository from the code that it
documents.

Thanks
Laszlo





Abner Chang
 

Thanks Mike and Laszlo for the comments.
I would have the readme markdown under RedfishPkg with SVG for the complex diagrams. PlantUML is good to the porting guide markdown for easy review.
Abner

-----Original Message-----
From: Kinney, Michael D [mailto:michael.d.kinney@intel.com]
Sent: Wednesday, April 7, 2021 4:30 AM
To: rfc@edk2.groups.io; lersek@redhat.com; Chang, Abner (HPS SW/FW
Technologist) <abner.chang@hpe.com>; Kinney, Michael D
<michael.d.kinney@intel.com>
Subject: RE: [edk2-rfc] [RFC] Documents under RedfishPkg

Hi Abner,

PlantUML is a way to embed some graphics in GitHub markdown text. Avoids
checking in SVG or BMP or PNG binaries.

INVALID URI REMOVED
3A__plantuml.com_&d=DwIGaQ&c=C5b8zRQO1miGmBeVZ2LFWg&r=_SN6F
ZBN4Vgi4Ulkskz6qU3NYRO03nHp9P7Z5q59A3E&m=dopb0lYExPus6V854vF8a
pisNnwzidkdZGS2XDjtA14&s=9nCqxY2Suxl1CLUlz-
Azhi6FWaZORPo3oQLiTfq4fI0&e=

INVALID URI REMOVED
3A__plantuml.com_en_guide&d=DwIGaQ&c=C5b8zRQO1miGmBeVZ2LFWg
&r=_SN6FZBN4Vgi4Ulkskz6qU3NYRO03nHp9P7Z5q59A3E&m=dopb0lYExPus6
V854vF8apisNnwzidkdZGS2XDjtA14&s=EjaowDShCFlt013uCcS-
QiSe0br8c9eGeLYMQyGKG0o&e=


Here is an example of using PlatUML from a Wiki page with the PlantUML
source text file also checked in.

https://github.com/tianocore-docs/edk2-
TemplateSpecification/wiki/TianoCore-Documents-GitBook-
Overview#introduction

GitHub Markdown source line that uses PlantUML server to convert
PlantUML source to a SVG when the page is viewed.

![GitBookOverview](INVALID URI REMOVED
3A__www.plantuml.com_plantuml_proxy-3Fsrc-3Dhttps-
3A__raw.githubusercontent.com_wiki_tianocore-2Ddocs_edk2-
2DTemplateSpecification_plantuml_GitBookOverview.puml&d=DwIGaQ&c=
C5b8zRQO1miGmBeVZ2LFWg&r=_SN6FZBN4Vgi4Ulkskz6qU3NYRO03nHp9P7
Z5q59A3E&m=dopb0lYExPus6V854vF8apisNnwzidkdZGS2XDjtA14&s=x2nZ6fZ
0N29Q5-WRynU6bf1vwK7pOrOID4cqIS41Rfw&e= )

PlantUML source file

INVALID URI REMOVED
3A__raw.githubusercontent.com_wiki_tianocore-2Ddocs_edk2-
2DTemplateSpecification_plantuml_GitBookOverview.puml&d=DwIGaQ&c=
C5b8zRQO1miGmBeVZ2LFWg&r=_SN6FZBN4Vgi4Ulkskz6qU3NYRO03nHp9P7
Z5q59A3E&m=dopb0lYExPus6V854vF8apisNnwzidkdZGS2XDjtA14&s=ToF_Ks
UzwXf97ohi5HZhARPubr7s1zqqrPnlSiSXUks&e=


Mike

-----Original Message-----
From: rfc@edk2.groups.io <rfc@edk2.groups.io> On Behalf Of Laszlo Ersek
Sent: Tuesday, April 6, 2021 7:06 AM
To: rfc@edk2.groups.io; abner.chang@hpe.com
Subject: Re: [edk2-rfc] [RFC] Documents under RedfishPkg

On 03/26/21 16:42, Abner Chang wrote:
Hi edk2 Stewards,
Is that ok to put some EDK2 Redfish port guide or design block diagrams in
a folder under RedfishPkg? e.g.
RedfishPkg/Documents?
Any practices we have on the current edk2 repo?
If you can add the documents in some text-based representation (markup
or plaintext), where "reviewing patches" will make sense in the future,
then I welcome adding the documentation under RedfishPkg.

(If you have diagrams, I think SVG might be good for those.)

Other packages have introduced porting and other accompanying
documentation in the wiki, but I find that inferior. I don't like it
when documentation lives in a separate repository from the code that it
documents.

Thanks
Laszlo