10 a.m.
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-sup...
--
Scott McCarty
Product Management - Containers, Red Hat Enterprise Linux & OpenShift
Email: smccarty(a)redhat.com
Phone: 312-660-3535
Cell: 330-807-1043
Web: http://crunchtools.com