Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources.
3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.git
Since I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
On 03/03/2017 09:57 AM, Jakub Hrozek wrote:
Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources. 3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.gitSince I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
I'm sorry but this seems wrong and over-complicated in modern world. At least new pages should be written in some document language (markdown?) and let pagure disaply it without manual conversion. If it can't do that then file a ticket.
On Fri, Mar 03, 2017 at 10:14:41AM +0100, Pavel Březina wrote:
On 03/03/2017 09:57 AM, Jakub Hrozek wrote:
Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources. 3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.gitSince I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
I'm sorry but this seems wrong and over-complicated in modern world. At least new pages should be written in some document language (markdown?)
It is written in RST. I just finished a first round, so you can very easily try it out: - dnf install python2-sphinx (only documentation builders need to do that) - clone https://pagure.io/jhrozek-doctest.git This is the documentation source in RST - go the the cloned directory and run make html. This gives you the rendered HTML - the rendered HTML can be viewed at https://pagure.io/docs/jhrozek-doctest/
and let pagure disaply it without manual conversion. If it can't do that then file a ticket.
Pagure can display rst directly, but sphinx can add additional sugar like rendering table of contents or links between pages. I'm not sure if pagure can do this on the fly on its own.
On (03/03/17 11:23), Jakub Hrozek wrote:
On Fri, Mar 03, 2017 at 10:14:41AM +0100, Pavel Březina wrote:
On 03/03/2017 09:57 AM, Jakub Hrozek wrote:
Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources. 3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.gitSince I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
I'm sorry but this seems wrong and over-complicated in modern world. At least new pages should be written in some document language (markdown?)
It is not such overcomplicated because it can be easily automated with git push hook. Maybe it is not possible atm in pagure. But we know pagure developers :-)
So in the end; you will/might just review pull request and merge it. just few clicks :-)
It is written in RST. I just finished a first round, so you can very easily try it out:
- dnf install python2-sphinx (only documentation builders need to do that)
- clone https://pagure.io/jhrozek-doctest.git This is the documentation source in RST
- go the the cloned directory and run make html. This gives you the rendered HTML
- the rendered HTML can be viewed at https://pagure.io/docs/jhrozek-doctest/
and let pagure disaply it without manual conversion. If it can't do that then file a ticket.
Pagure can display rst directly, but sphinx can add additional sugar like rendering table of contents or links between pages. I'm not sure if pagure can do this on the fly on its own.
Agree
http://blog.samalik.com/fedora-modularity-documentation/
LS
On 03/03/2017 05:30 PM, Lukas Slebodnik wrote:
On (03/03/17 11:23), Jakub Hrozek wrote:
On Fri, Mar 03, 2017 at 10:14:41AM +0100, Pavel Březina wrote:
On 03/03/2017 09:57 AM, Jakub Hrozek wrote:
Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources. 3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.gitSince I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
I'm sorry but this seems wrong and over-complicated in modern world. At least new pages should be written in some document language (markdown?)
It is not such overcomplicated because it can be easily automated with git push hook. Maybe it is not possible atm in pagure. But we know pagure developers :-)
So in the end; you will/might just review pull request and merge it. just few clicks :-)
It is written in RST. I just finished a first round, so you can very easily try it out:
- dnf install python2-sphinx (only documentation builders need to do that)
- clone https://pagure.io/jhrozek-doctest.git This is the documentation source in RST
- go the the cloned directory and run make html. This gives you the rendered HTML
- the rendered HTML can be viewed at https://pagure.io/docs/jhrozek-doctest/
and let pagure disaply it without manual conversion. If it can't do that then file a ticket.
Pagure can display rst directly, but sphinx can add additional sugar like rendering table of contents or links between pages. I'm not sure if pagure can do this on the fly on its own.
Agree
Are we going to have something like this? https://docs.pagure.org/modularity/
That would be nice.
On Thu, Mar 16, 2017 at 12:01:09PM +0100, Pavel Březina wrote:
Are we going to have something like this? https://docs.pagure.org/modularity/
Yes, that's the plan for spring. I would like to first migrate the docs, then create a landing page. Mostly because to many people (even those familiar with Fedora/RHEL), it is not apparent that SSSD is no longer just an LDAP client, so we need to explain the secrets component, KCM etc.
We also have the sssd.io domain reserved.
On Fri, Mar 3, 2017 at 9:57 AM, Jakub Hrozek jhrozek@redhat.com wrote:
Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources. 3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.gitSince I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
I don't disagree but I also don't think the approach is optimal (but well, we have been working together it Pagure guys in order to make it optimal at some point).
Having a way to edit the docs similarly to what we had in Fedora host sounds better. But here I'm not sure if it was really better or if it is just something different that we will get used to.
Having the docs in a separate git repo makes me think that at least one review will be done for any change in the repo and it's, at least for me, a good thing.
So, please, go ahead with your approach and let's give it a try.
Best Regards, -- Fabiano Fidêncio
On (03/03/17 12:50), Fabiano Fidêncio wrote:
On Fri, Mar 3, 2017 at 9:57 AM, Jakub Hrozek jhrozek@redhat.com wrote:
Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources. 3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.gitSince I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
I don't disagree but I also don't think the approach is optimal (but well, we have been working together it Pagure guys in order to make it optimal at some point).
Having a way to edit the docs similarly to what we had in Fedora host sounds better. But here I'm not sure if it was really better or if it is just something different that we will get used to.
We need to get used to that pagure issues != trac and pagure docs != wiki. And I would like to avoid maintaining wiki ourself.
BTW if somebody know about alternative to sphinx wich can convert wiki -> html then we can still use wiki.
LS
On Fri, Mar 03, 2017 at 12:50:11PM +0100, Fabiano Fidêncio wrote:
On Fri, Mar 3, 2017 at 9:57 AM, Jakub Hrozek jhrozek@redhat.com wrote:
Hi,
I started on migrating the wiki content from fedorahosted to pagure. Because we are working hard on finishing the 1.15.1 and 1.15.2 releases, I want to only migrate the content that we need right now, which is the releases page (so that we can put the release notes somewhere) and design pages for 1.15 features.
So far I was trying the documentation out in a sandbox repo: https://pagure.io/docs/jhrozek-doctest/ I think it looks OK and I like the rst->sphinx->html workflow: https://docs.pagure.org/pagure/usage/using_doc.html
Regarding the repositories, I propose we do this: 1) create a new repo under the SSSD namespace, perhaps: https://pagure.io/SSSD/docs This repo will only contain the rst sources. I would like to ask Patrick to mirror this repo to github so we can use PRs to update documentation.
2) When a PR to this repo is merged, one of the maintainers will run "make html" in the docs repo. This will generate HTML documentation from the rst sources. 3) This HTML documentation will be pushed to: ssh://git@pagure.io/docs/SSSD/sssd.gitSince I would only like to put up the releases and changelogs for now, I would like to ask to temporarily not review the RST changes with PRs until we are done with 1.15 development.
Please speak up if you disagree :-)
I don't disagree but I also don't think the approach is optimal (but well, we have been working together it Pagure guys in order to make it optimal at some point).
Having a way to edit the docs similarly to what we had in Fedora host sounds better. But here I'm not sure if it was really better or if it is just something different that we will get used to.
Here I was thinking that (especially for non-technical folks), editing the RST files in some web-based browser on github makes sense. They could even open a PR directly from github w/o opening a terminal and cloning the RST repo.
sssd-devel@lists.fedorahosted.org
-
Fabiano Fidêncio -
Jakub Hrozek -
Lukas Slebodnik -
Pavel Březina