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.
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.
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.
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?)
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"]
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
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