From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 355FD1FF380 for ; Fri, 19 Apr 2024 11:05:52 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 15C333322; Fri, 19 Apr 2024 11:05:44 +0200 (CEST) From: Christoph Heiss To: pve-devel@lists.proxmox.com Date: Fri, 19 Apr 2024 11:05:06 +0200 Message-ID: <20240419090519.291775-1-c.heiss@proxmox.com> X-Mailer: git-send-email 2.44.0 MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.001 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pve-devel] [RFC PATCH docs{, -common} 0/13] introduce common documentation base X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" 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