[pve-devel] [RFC PATCH docs{, -common} 0/13] introduce common documentation base

[Christoph Heiss <c.heiss@proxmox.com>]

tl;dr: Introduce a separate repository for shared documentation between
all three products.

This proposes the introduction of a - aptly named - proxmox-docs-common
repo, which can be used for all documentation not specific to a single
product.

Marked RFC to gather feedback from other people. After talking to some
people off-list, there definitely is the need for something like this in
the long run.

For now, this is pve-docs only, with only one page and two partials (see
also "Organization"). But it shows the purpose and general approach well
enough to gather some first feedback.

Motivation
==========
A lot of pages and sections esp. from pve-docs apply to all three
products. To name a few; package repos, (firmware) updates, network
config, ZFS host administration, bootloader etc. etc.

Further, the documentation for the auto-installer from Aaron (now in the
wiki) and for the notification system from Lukas would also be good fit
for proxmox-docs-common.

The plan would be to gradually move them all into proxmox-docs-common as
appropriate, thus de-duplicating and having them available on all three
products without the headaches of copying & keeping them in sync.

Most of the common documentation is now done via the wiki, but this
approach would allow "codifying" these things - generating wiki pages
from our documentation is a solved problem already.

Organization
============
Pretty simple; all files in the repo root of proxmox-docs-common
represent "full pages", i.e. starting with a level-1 heading, much like
in pve-docs. These must still each be included somewhere, e.g. for
pve-docs the appropriate subpage or in `pve-admin-guide.adoc`.

Additionally, there is the `partials/` folder, which contains exactly
that - these are sections of pages (aka. with no level-1 heading) that
can be shared, but where the whole page might might not be suitable for
sharing. These can be then included as usual using

  include::proxmox-docs-common/partials/foo.adoc[]

The distinction is only for organization in the repo itself, but
otherwise has no special/hidden meaning. So this can easily be
changed/dropped if desired.

Future works
============
- Integrating into pmg-docs
- Integrating ReStructuredText
- Integrating into proxmox-backup documentation
- Moving more pages and sections into it, of course - lots to be done
  there
- Unifying the `scan-adoc-refs` tool from {pve,pmg}-docs in the common
  repo

AsciiDoc vs. ReStructuredText
=============================
Currently, this is AsciiDoc only.

My proposal would be to keep all exisiting AsciiDoc pages as such and
only adapt as necessary. Since it is possible to automatically convert
between AsciiDoc and ReStructuredText, this means we can reuse
existing AsciiDoc-written pages/partials in PBS and write new pages in
ReStructuredText.

The latter is not included in this series yet, but would be a follow-up
in the future, to keep this initial change as simple as possible.

[ Of course, one could also think about mechanically converting all
  AsciiDoc-written pages to ReStructuredText, but that's a whole
  different story and harder to get right. ]

Diffstats
=========
Looks a bit scary, but the bulk of it are simply renames & pulling
sections out into different files. For the latter, there is always a
commit for copying the content 1:1 and one adapting small things as
necessary.

pve-docs:

Christoph Heiss (7):
  gitmodules: add proxmox-docs-common
  scan-adoc-refs: enable building pages from proxmox-docs-common/ subdir
  images: strip `pve-` prefix from screenshots used in common docs
  asciidoc: conf: add iso-url variable
  installation-media: move to common docs
  installation: use new 'installation-flow' partial from common docs
  installation: use new 'advanced-installation' partial from common docs

 .gitmodules                                   |   3 +
 Makefile                                      |   6 +-
 asciidoc/asciidoc-pve.conf                    |   3 +
 .../{pve-grub-menu.png => grub-menu.png}      | Bin
 .../{pve-grub-menu.ppm => grub-menu.ppm}      | Bin
 ...nstall-summary.png => install-summary.png} | Bin
 ...nstall-summary.ppm => install-summary.ppm} | Bin
 ...{pve-installation.png => installation.png} | Bin
 ...{pve-installation.ppm => installation.ppm} | Bin
 ...elect-location.png => select-location.png} | Bin
 ...elect-location.ppm => select-location.ppm} | Bin
 ...target-disk.png => select-target-disk.png} | Bin
 ...target-disk.ppm => select-target-disk.ppm} | Bin
 ...{pve-set-password.png => set-password.png} | Bin
 ...{pve-set-password.ppm => set-password.ppm} | Bin
 ...ve-setup-network.png => setup-network.png} | Bin
 ...ve-setup-network.ppm => setup-network.ppm} | Bin
 ...ve-tui-installer.png => tui-installer.png} | Bin
 ...ve-tui-installer.ppm => tui-installer.ppm} | Bin
 png-verify.pl                                 |  14 +-
 proxmox-docs-common                           |   1 +
 pve-doc-generator.mk.in                       |   6 +
 pve-installation-media.adoc                   | 132 --------
 pve-installation.adoc                         | 300 +-----------------
 scan-adoc-refs                                |  25 +-
 25 files changed, 44 insertions(+), 446 deletions(-)
 create mode 100644 .gitmodules
 rename images/screenshot/{pve-grub-menu.png => grub-menu.png} (100%)
 rename images/screenshot/{pve-grub-menu.ppm => grub-menu.ppm} (100%)
 rename images/screenshot/{pve-install-summary.png => install-summary.png} (100%)
 rename images/screenshot/{pve-install-summary.ppm => install-summary.ppm} (100%)
 rename images/screenshot/{pve-installation.png => installation.png} (100%)
 rename images/screenshot/{pve-installation.ppm => installation.ppm} (100%)
 rename images/screenshot/{pve-select-location.png => select-location.png} (100%)
 rename images/screenshot/{pve-select-location.ppm => select-location.ppm} (100%)
 rename images/screenshot/{pve-select-target-disk.png => select-target-disk.png} (100%)
 rename images/screenshot/{pve-select-target-disk.ppm => select-target-disk.ppm} (100%)
 rename images/screenshot/{pve-set-password.png => set-password.png} (100%)
 rename images/screenshot/{pve-set-password.ppm => set-password.ppm} (100%)
 rename images/screenshot/{pve-setup-network.png => setup-network.png} (100%)
 rename images/screenshot/{pve-setup-network.ppm => setup-network.ppm} (100%)
 rename images/screenshot/{pve-tui-installer.png => tui-installer.png} (100%)
 rename images/screenshot/{pve-tui-installer.ppm => tui-installer.ppm} (100%)
 create mode 160000 proxmox-docs-common
 delete mode 100644 pve-installation-media.adoc

proxmox-docs-common:

Christoph Heiss (6):
  installation-media: move page from pve-docs here
  installation-media: adapt for common usage
  partials: add installation flow from pve-docs
  partials: installation-flow: adapt from pve-docs
  partials: add advanced installation hints from pve-docs
  partials: advanced-installation: adapt from pve-docs

 installation-media.adoc             |  21 +++++++++++++++++++++++++++--
 partials/advanced-installation.adoc | 125 ++++++++++++++++++++
 partials/installation-flow.adoc     | 171 ++++++++++++++++++++++++++++
 3 files changed, 440 insertions(+), 9 deletions(-)
 create mode 100644 installation-media.adoc
 create mode 100644 partials/advanced-installation.adoc
 create mode 100644 partials/installation-flow.adoc

--
2.42.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel