As pre-announced on the centos-devel list in another thread, and also per Automotive SIG request (https://pagure.io/centos-infra/issue/458) , we'd like to announce new https://sigs.centos.org virtual host, rendering SIG documentation (if they want to)
The system is based on markdown documents, rendered through mkdocs (https://mkdocs.org)
How can you request your SIG namespace on it ?
# prepare a git repository with your .md files and a mkdocs.yml file (see https://www.mkdocs.org/getting-started/) # create a centos-infra ticket on https://pagure.io/centos-infra/issues with : - sig name and description - git origin for your project (where your .md files are stored) : it can be wherever you want, so github, gitlab, pagure.io or even git.centos.org if you ask for a project to be created there for your SIG # once created (by ansible), your content will be automatically rendered and visible under https://sigs.centos.org/<sig_name> (example : https://sigs.centos.org/hyperscale/ , already "live")
Once you'll have just accepted PR or pushed commits to your git repository, it will be picked up, rendered and push to https://sigs.centos.org vhost.
Suggestion : if your SIG has such documentation online, it would be good to just have a pointer in wiki to the new place, (or even move instructions - if you have some - to the dedicated SIG doc site)
This is awesome. Thanks for making this happen.
Can anyone submit those centos-infra tickets pointing to the documentation or does that need to be done by a SIG member?
Thanks, Jack
On Wed, Sep 29, 2021 at 6:12 AM Fabian Arrotin arrfab@centos.org wrote:
As pre-announced on the centos-devel list in another thread, and also per Automotive SIG request (https://pagure.io/centos-infra/issue/458) , we'd like to announce new https://sigs.centos.org virtual host, rendering SIG documentation (if they want to)
The system is based on markdown documents, rendered through mkdocs (https://mkdocs.org)
How can you request your SIG namespace on it ?
# prepare a git repository with your .md files and a mkdocs.yml file (see https://www.mkdocs.org/getting-started/) # create a centos-infra ticket on https://pagure.io/centos-infra/issues with :
- sig name and description
- git origin for your project (where your .md files are stored) : it
can be wherever you want, so github, gitlab, pagure.io or even git.centos.org if you ask for a project to be created there for your SIG # once created (by ansible), your content will be automatically rendered and visible under https://sigs.centos.org/<sig_name> (example : https://sigs.centos.org/hyperscale/ , already "live")
Once you'll have just accepted PR or pushed commits to your git repository, it will be picked up, rendered and push to https://sigs.centos.org vhost.
Suggestion : if your SIG has such documentation online, it would be good to just have a pointer in wiki to the new place, (or even move instructions - if you have some - to the dedicated SIG doc site)
-- Fabian Arrotin The CentOS Project | https://www.centos.org gpg key: 17F3B7A1 | twitter: @arrfab
CentOS-devel mailing list CentOS-devel@centos.org https://lists.centos.org/mailman/listinfo/centos-devel
On 01/10/2021 19:35, Jack Aboutboul wrote:
This is awesome. Thanks for making this happen.
Can anyone submit those centos-infra tickets pointing to the documentation or does that need to be done by a SIG member?
Thanks, Jack
Hi Jack,
If you mean asking for namespace on sigs.centos.org, yes that would have to come from an approved SIG member. Had you something in mind ?
BTW, if some people using SIG content/rpm packages (can be also from AlmaLinux/RockyLinux/else) but not participating (yet) to SIG itself (at the packaging level), are interesting in helping with this , they can also engage directly with the SIG to propose to write and maintain the doc (like the "how to use packages from $SIG"), and so participate in the ecosystem ;-)
On Wed, Sep 29, 2021 at 6:12 AM Fabian Arrotin arrfab@centos.org wrote:
The system is based on markdown documents, rendered through mkdocs (https://mkdocs.org)
Out of curiosity, would there be anything to gain using Antora over MkDocs? Only asking as that's what the Fedora and CentOS ecosystem documentation sites seem to be built with.
Really glad this is now available for sigs, thanks Fabian and the infra team!
On 01/10/2021 20:38, Mike Rochefort wrote:
On Wed, Sep 29, 2021 at 6:12 AM Fabian Arrotin arrfab@centos.org wrote:
The system is based on markdown documents, rendered through mkdocs (https://mkdocs.org)
Out of curiosity, would there be anything to gain using Antora over MkDocs? Only asking as that's what the Fedora and CentOS ecosystem documentation sites seem to be built with.
Well, we (CentOS Infra SIG) like markdown and so reason why we decided to use mkdocs for https://docs.infra.centos.org :-) We got the request from Automotive SIG to also use it so reason why we thought about offering it for other SIGs.
We don't use Antora (I don't like it myself but this is my personal opinion so not reflecting the project) even if https://docs.centos.org is built with it (to be clear : we offer the hosting service there, but we don't even build it : it's rendered elsewhere and then pushed to that node)
Now if some SIGs would like to use Antora, Jekyll, or else, that would be *trivial* to just adapt our ansible role and ansible variable/list to also point to a specific container/build command and so select in the list the rendering system :-)
On Sat, Oct 2, 2021 at 3:24 AM Fabian Arrotin arrfab@centos.org wrote:
Now if some SIGs would like to use Antora, Jekyll, or else, that would be *trivial* to just adapt our ansible role and ansible variable/list to also point to a specific container/build command and so select in the list the rendering system :-)
Oh, cool. I wasn't sure how this worked and if the pipeline was more tightly tied to the use of MkDocs. Thanks for the added information!
On Sat, Oct 02, 2021 at 09:24:08AM +0200, Fabian Arrotin wrote:
We don't use Antora (I don't like it myself but this is my personal opinion so not reflecting the project) even if https://docs.centos.org is built with it (to be clear : we offer the hosting service there, but we don't even build it : it's rendered elsewhere and then pushed to that node)
I definitely understand the preference for Markdown for simple docs. Asciidoc has some weird choices (URL syntax is even uglier than Markdown, which is saying something; handling of formatting and punctuation is a little ungainly, etc.)
It has some really nice features for more complicated docs, and things like Admonitions are super-nice for ... well, computer docs. There are also some things like macros which we don't use enough in Fedora Docs but I'd like to more.
Since I hope docs — and SIG work in general, really — are areas where Fedora and CentOS can increasingly collaborate, I'd really like to see as much working in the same way as possible around these kinds of things!
-
Fabian Arrotin -
Jack Aboutboul -
Matthew Miller -
Mike Rochefort