All, I chatted with Mehul today and I want to start a conversation around how we could improve the docs. Here are my thoughts: 1. Figure out a way to keep the main page canonical sources on https://github.com/containers/podman/tree/main/docs/source/markdown 2. Synchronize https://github.com/containers/podman/docs/source/markdown <https://github.com/containers/podman/tree/main/docs/source/markdown> to github.com/containers/podman.io/docs/source/markdown <http://github.com/containers/podman.io/docs> 3. Let's move everything else from github.com/containers/podman/docs <http://github.com/containers/podman/docs/source/markdown> over to the github.com/containers/podman.io/docs 4. Update the theme to this new theme Mehul tested [1] call furo. Feel free to test that container image. It pulls the content from the current repository. 5. If we do #3, we can make it easier for people to commit docs because it wouldn't need to go through the full CI/CD gating tests (might not be correct. Is the podman.io repository gated by the same CI/CD?) 6. Second, we could have dedicated editors instead of engineers approve docs changes An alternative to this proposal could be to use a completely new repository apart from podman.io. If we can separate the docs out, I think we could find volunteers to be editors (aka approve PRs). This would allow core code contributors to focus on code, and docs volunteers to focus on docs. Stated another way, I don't think docs needs CI/CD like code. I think editors probably do a better job (though CI/CD could be useful for link checking, etc). Thoughts? [1]: FROM fedora:latest EXPOSE 8000 RUN dnf install -y gpgme-devel \ libseccomp-devel.x86_64 \ systemd-devel \ make \ git \ golang \ python \ && export PKG_CONFIG_PATH="/usr/lib/pkgconfig" RUN cd / && git clone https://github.com/containers/podman.git \ && cd podman \ && make install.tools RUN cd /podman/docs \ && dnf -y install python3-sphinx python3-recommonmark \ && pip install sphinx-markdown-tables furo \ && sed -i 's|html_theme = "alabaster"|html_theme = "furo"|g' /podman/docs/source/conf.py \ && make html WORKDIR /podman/docs CMD ["python", "-m", "http.server", "8000", "--directory", "build/html"] Best Regards Scott M -- -- 18 ways to differentiate open source products from upstream suppliers: https://opensource.com/article/21/2/differentiating-products-upstream-suppli... -- Scott McCarty Product Management - Containers, Red Hat Enterprise Linux & OpenShift Email: smccarty@redhat.com Phone: 312-660-3535 Cell: 330-807-1043 Web: http://crunchtools.com
Hi, This sounds really cool, I'd love to be a part of it. Regards, Leon On Fri, 17 Sep, 2021, 20:32 Scott McCarty, <smccarty@redhat.com> wrote:
All, I chatted with Mehul today and I want to start a conversation around how we could improve the docs. Here are my thoughts:
1. Figure out a way to keep the main page canonical sources on https://github.com/containers/podman/tree/main/docs/source/markdown 2. Synchronize https://github.com/containers/podman/docs/source/markdown <https://github.com/containers/podman/tree/main/docs/source/markdown> to github.com/containers/podman.io/docs/source/markdown <http://github.com/containers/podman.io/docs> 3. Let's move everything else from github.com/containers/podman/docs <http://github.com/containers/podman/docs/source/markdown> over to the github.com/containers/podman.io/docs 4. Update the theme to this new theme Mehul tested [1] call furo. Feel free to test that container image. It pulls the content from the current repository. 5. If we do #3, we can make it easier for people to commit docs because it wouldn't need to go through the full CI/CD gating tests (might not be correct. Is the podman.io repository gated by the same CI/CD?) 6. Second, we could have dedicated editors instead of engineers approve docs changes
An alternative to this proposal could be to use a completely new repository apart from podman.io. If we can separate the docs out, I think we could find volunteers to be editors (aka approve PRs). This would allow core code contributors to focus on code, and docs volunteers to focus on docs. Stated another way, I don't think docs needs CI/CD like code. I think editors probably do a better job (though CI/CD could be useful for link checking, etc).
Thoughts?
[1]: FROM fedora:latest
EXPOSE 8000 RUN dnf install -y gpgme-devel \ libseccomp-devel.x86_64 \ systemd-devel \ make \ git \ golang \ python \ && export PKG_CONFIG_PATH="/usr/lib/pkgconfig"
RUN cd / && git clone https://github.com/containers/podman.git \ && cd podman \ && make install.tools
RUN cd /podman/docs \ && dnf -y install python3-sphinx python3-recommonmark \ && pip install sphinx-markdown-tables furo \ && sed -i 's|html_theme = "alabaster"|html_theme = "furo"|g' /podman/docs/source/conf.py \ && make html
WORKDIR /podman/docs
CMD ["python", "-m", "http.server", "8000", "--directory", "build/html"]
Best Regards Scott M
--
--
18 ways to differentiate open source products from upstream suppliers: https://opensource.com/article/21/2/differentiating-products-upstream-suppli... --
Scott McCarty Product Management - Containers, Red Hat Enterprise Linux & OpenShift Email: smccarty@redhat.com Phone: 312-660-3535 Cell: 330-807-1043 Web: http://crunchtools.com
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
On 9/17/21 11:15, Leon N wrote:
Hi,
This sounds really cool, I'd love to be a part of it.
Regards, Leon
On Fri, 17 Sep, 2021, 20:32 Scott McCarty, <smccarty@redhat.com> wrote:
All, I chatted with Mehul today and I want to start a conversation around how we could improve the docs. Here are my thoughts:
BTW, we did do some fixes to clean up the commands parts of the docs, this past week.
1. Figure out a way to keep the main page canonical sources on https://github.com/containers/podman/tree/main/docs/source/markdown 2. Synchronize https://github.com/containers/podman/docs/source/markdown <https://github.com/containers/podman/tree/main/docs/source/markdown> to github.com/containers/podman.io/docs/source/markdown <http://github.com/containers/podman.io/docs> 3. Let's move everything else from github.com/containers/podman/docs <http://github.com/containers/podman/docs/source/markdown> over to the github.com/containers/podman.io/docs <http://github.com/containers/podman.io/docs> 4. Update the theme to this new theme Mehul tested [1] call furo. Feel free to test that container image. It pulls the content from the current repository. 5. If we do #3, we can make it easier for people to commit docs because it wouldn't need to go through the full CI/CD gating tests (might not be correct. Is the podman.io <http://podman.io> repository gated by the same CI/CD?) 6. Second, we could have dedicated editors instead of engineers approve docs changes
Difficult to implement. I don't want PRs being blocked, because we can't get DOC editors to approve man page changes.
An alternative to this proposal could be to use a completely new repository apart from podman.io <http://podman.io>. If we can separate the docs out, I think we could find volunteers to be editors (aka approve PRs). This would allow core code contributors to focus on code, and docs volunteers to focus on docs. Stated another way, I don't think docs needs CI/CD like code. I think editors probably do a better job (though CI/CD could be useful for link checking, etc).
Not sure how you handle man pages, which are the core piece of Docs, but updated all of the time by engineers.
Thoughts?
[1]: FROM fedora:latest
EXPOSE 8000 RUN dnf install -y gpgme-devel \ libseccomp-devel.x86_64 \ systemd-devel \ make \ git \ golang \ python \ && export PKG_CONFIG_PATH="/usr/lib/pkgconfig"
RUN cd / && git clonehttps://github.com/containers/podman.git \ && cd podman \ && make install.tools
RUN cd /podman/docs \ && dnf -y install python3-sphinx python3-recommonmark \ && pip install sphinx-markdown-tables furo \ && sed -i 's|html_theme = "alabaster"|html_theme = "furo"|g' /podman/docs/source/conf.py \ && make html
WORKDIR /podman/docs
CMD ["python", "-m", "http.server", "8000", "--directory", "build/html"]
Best Regards Scott M
--
--
18 ways to differentiate open source products from upstream suppliers:https://opensource.com/article/21/2/differentiating-products-upstream-suppli... --
Scott McCarty Product Management - Containers, Red Hat Enterprise Linux & OpenShift Email: smccarty@redhat.com Phone: 312-660-3535 Cell: 330-807-1043 Web: http://crunchtools.com
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
_______________________________________________ Podman mailing list --podman@lists.podman.io To unsubscribe send an email topodman-leave@lists.podman.io
Hey All, A few comments. Currently github.com/containers/podman.io does not have CI checking, that may be something that we change in the future. So the barrier to entry in making a PR there is lower than to the Podman GitHub repository. One thing to consider about moving the docs from podman to podman.io is indeed the CI checking in podman. In addition to the CI checking for new tests, only docs, etc., the CI also checks to make sure that if a new option is added, either to a man page or to the code, then it must be in both places or the PR fails the smoke test. That's something that would be hard to emulate if the docs were across two projects, so we'd lose that functionality. Perhaps the payback from the move pays for that loss, IDK. I do know that we've had a few instances of the CI failing a PR due to the man page not being updated. All that said, I'm not against the moved. From a logical standpoint, it makes sense to me that you'd find the docs in 'docs.podman.io' in the podman.io project. t On 9/18/21 8:37 AM, Daniel Walsh wrote:
On 9/17/21 11:15, Leon N wrote:
Hi,
This sounds really cool, I'd love to be a part of it.
Regards, Leon
On Fri, 17 Sep, 2021, 20:32 Scott McCarty, <smccarty@redhat.com> wrote:
All, I chatted with Mehul today and I want to start a conversation around how we could improve the docs. Here are my thoughts:
BTW, we did do some fixes to clean up the commands parts of the docs, this past week.
1. Figure out a way to keep the main page canonical sources on https://github.com/containers/podman/tree/main/docs/source/markdown 2. Synchronize https://github.com/containers/podman/docs/source/markdown <https://github.com/containers/podman/tree/main/docs/source/markdown> to github.com/containers/podman.io/docs/source/markdown <http://github.com/containers/podman.io/docs> 3. Let's move everything else from github.com/containers/podman/docs <http://github.com/containers/podman/docs/source/markdown> over to the github.com/containers/podman.io/docs <http://github.com/containers/podman.io/docs> 4. Update the theme to this new theme Mehul tested [1] call furo. Feel free to test that container image. It pulls the content from the current repository. 5. If we do #3, we can make it easier for people to commit docs because it wouldn't need to go through the full CI/CD gating tests (might not be correct. Is the podman.io <http://podman.io> repository gated by the same CI/CD?) 6. Second, we could have dedicated editors instead of engineers approve docs changes
Difficult to implement. I don't want PRs being blocked, because we can't get DOC editors to approve man page changes.
An alternative to this proposal could be to use a completely new repository apart from podman.io <http://podman.io>. If we can separate the docs out, I think we could find volunteers to be editors (aka approve PRs). This would allow core code contributors to focus on code, and docs volunteers to focus on docs. Stated another way, I don't think docs needs CI/CD like code. I think editors probably do a better job (though CI/CD could be useful for link checking, etc).
Not sure how you handle man pages, which are the core piece of Docs, but updated all of the time by engineers.
Thoughts?
[1]: FROM fedora:latest
EXPOSE 8000 RUN dnf install -y gpgme-devel \ libseccomp-devel.x86_64 \ systemd-devel \ make \ git \ golang \ python \ && export PKG_CONFIG_PATH="/usr/lib/pkgconfig"
RUN cd / && git clonehttps://github.com/containers/podman.git \ && cd podman \ && make install.tools
RUN cd /podman/docs \ && dnf -y install python3-sphinx python3-recommonmark \ && pip install sphinx-markdown-tables furo \ && sed -i 's|html_theme = "alabaster"|html_theme = "furo"|g' /podman/docs/source/conf.py \ && make html
WORKDIR /podman/docs
CMD ["python", "-m", "http.server", "8000", "--directory", "build/html"]
Best Regards Scott M
--
--
18 ways to differentiate open source products from upstream suppliers:https://opensource.com/article/21/2/differentiating-products-upstream-suppli... --
Scott McCarty Product Management - Containers, Red Hat Enterprise Linux & OpenShift Email: smccarty@redhat.com Phone: 312-660-3535 Cell: 330-807-1043 Web: http://crunchtools.com
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
_______________________________________________ Podman mailing list --podman@lists.podman.io To unsubscribe send an email topodman-leave@lists.podman.io
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
Tom, Is it a crazy idea to propose this as a discussion item for the next Community Cabal similar to what we did for Podman Desktop? Or, perhaps even a separate one-off? I think it would be useful to explore if there are workarounds for, as you mention, spanning two repos. Best Regards Scott M On Sat, Sep 18, 2021 at 12:59 PM Tom Sweeney <tom.sweeney@redhat.com> wrote:
Hey All,
A few comments. Currently github.com/containers/podman.io does not have CI checking, that may be something that we change in the future. So the barrier to entry in making a PR there is lower than to the Podman GitHub repository.
One thing to consider about moving the docs from podman to podman.io is indeed the CI checking in podman. In addition to the CI checking for new tests, only docs, etc., the CI also checks to make sure that if a new option is added, either to a man page or to the code, then it must be in both places or the PR fails the smoke test. That's something that would be hard to emulate if the docs were across two projects, so we'd lose that functionality. Perhaps the payback from the move pays for that loss, IDK. I do know that we've had a few instances of the CI failing a PR due to the man page not being updated.
All that said, I'm not against the moved. From a logical standpoint, it makes sense to me that you'd find the docs in 'docs.podman.io' in the podman.io project.
t
On 9/18/21 8:37 AM, Daniel Walsh wrote:
On 9/17/21 11:15, Leon N wrote:
Hi,
This sounds really cool, I'd love to be a part of it.
Regards, Leon
On Fri, 17 Sep, 2021, 20:32 Scott McCarty, <smccarty@redhat.com> wrote:
All, I chatted with Mehul today and I want to start a conversation around how we could improve the docs. Here are my thoughts:
BTW, we did do some fixes to clean up the commands parts of the docs, this past week.
1. Figure out a way to keep the main page canonical sources on https://github.com/containers/podman/tree/main/docs/source/markdown 2. Synchronize https://github.com/containers/podman/docs/source/markdown <https://github.com/containers/podman/tree/main/docs/source/markdown> to github.com/containers/podman.io/docs/source/markdown <http://github.com/containers/podman.io/docs> 3. Let's move everything else from github.com/containers/podman/docs <http://github.com/containers/podman/docs/source/markdown> over to the github.com/containers/podman.io/docs 4. Update the theme to this new theme Mehul tested [1] call furo. Feel free to test that container image. It pulls the content from the current repository. 5. If we do #3, we can make it easier for people to commit docs because it wouldn't need to go through the full CI/CD gating tests (might not be correct. Is the podman.io repository gated by the same CI/CD?) 6. Second, we could have dedicated editors instead of engineers approve docs changes
Difficult to implement. I don't want PRs being blocked, because we can't get DOC editors to approve man page changes.
An alternative to this proposal could be to use a completely new
repository apart from podman.io. If we can separate the docs out, I think we could find volunteers to be editors (aka approve PRs). This would allow core code contributors to focus on code, and docs volunteers to focus on docs. Stated another way, I don't think docs needs CI/CD like code. I think editors probably do a better job (though CI/CD could be useful for link checking, etc).
Not sure how you handle man pages, which are the core piece of Docs, but updated all of the time by engineers.
Thoughts?
[1]: FROM fedora:latest
EXPOSE 8000 RUN dnf install -y gpgme-devel \ libseccomp-devel.x86_64 \ systemd-devel \ make \ git \ golang \ python \ && export PKG_CONFIG_PATH="/usr/lib/pkgconfig"
RUN cd / && git clone https://github.com/containers/podman.git \ && cd podman \ && make install.tools
RUN cd /podman/docs \ && dnf -y install python3-sphinx python3-recommonmark \ && pip install sphinx-markdown-tables furo \ && sed -i 's|html_theme = "alabaster"|html_theme = "furo"|g' /podman/docs/source/conf.py \ && make html
WORKDIR /podman/docs
CMD ["python", "-m", "http.server", "8000", "--directory", "build/html"]
Best Regards Scott M
--
--
18 ways to differentiate open source products from upstream suppliers: https://opensource.com/article/21/2/differentiating-products-upstream-suppli... --
Scott McCarty Product Management - Containers, Red Hat Enterprise Linux & OpenShift Email: smccarty@redhat.com Phone: 312-660-3535 Cell: 330-807-1043 Web: http://crunchtools.com
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
_______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
-- -- 18 ways to differentiate open source products from upstream suppliers: https://opensource.com/article/21/2/differentiating-products-upstream-suppli... -- Scott McCarty Product Management - Containers, Red Hat Enterprise Linux & OpenShift Email: smccarty@redhat.com Phone: 312-660-3535 Cell: 330-807-1043 Web: http://crunchtools.com
participants (4)
-
Daniel Walsh -
Leon N -
Scott McCarty -
Tom Sweeney