From 58d28147ddb97dc9f5c26e8f6b529da464481582 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Floure?= Date: Fri, 3 Jun 2022 09:14:47 +0200 Subject: [PATCH] Refresh website content, add contrib docs to the generation pipeline --- Makefile | 14 +- src/_static/custom.css | 5 + src/cdist-changelog.rst | 17 ++ src/cdist-documentation.rst | 35 +++- src/cdist-features.rst | 2 +- src/cdist-install.rst | 167 ---------------- ...t-manual.rst => cdist-manual-archives.rst} | 9 +- src/cdist-os.rst | 19 -- src/cdist-speeches.rst | 9 - src/cdist-support.rst | 31 --- src/cdist-upgrade.rst | 188 ------------------ src/cdist-why.rst | 10 +- src/conf.py | 8 +- src/index.rst | 36 +++- 14 files changed, 103 insertions(+), 447 deletions(-) delete mode 100644 src/cdist-install.rst rename src/{cdist-manual.rst => cdist-manual-archives.rst} (95%) delete mode 100644 src/cdist-os.rst delete mode 100644 src/cdist-speeches.rst delete mode 100644 src/cdist-support.rst delete mode 100644 src/cdist-upgrade.rst diff --git a/Makefile b/Makefile index af55b989..69d9e8d7 100644 --- a/Makefile +++ b/Makefile @@ -7,14 +7,19 @@ WEBSITE_REMOTE_DIR=/home/services/www/nico/www.cdi.st/www/ WEBSITE_MANUALS_DIR="$(WEBSITE_SRC_DIR)/extra/manual" CDIST_DIR=../cdist +CDIST_CONTRIB_DIR=../cdist-contrib CDIST_DOCS_DIR="$(CDIST_DIR)/docs" +CDIST_CONTRIB_DOCS_DIR="$(CDIST_CONTRIB_DIR)/docs" CDIST_HELPER="$(CDIST_DIR)/bin/cdist-build-helper" CDIST_CHANGELOG_VERSION=$(shell $(CDIST_HELPER) changelog-version) CDIST_CHANGELOG_FILE="$(CDIST_DOCS_DIR)/changelog" CDIST_DOCS_HTML_DIST_DIR="$(CDIST_DOCS_DIR)/dist/html" +CDIST_CONTRIB_DOCS_HTML_DIST_DIR="$(CDIST_CONTRIB_DOCS_DIR)/dist/html" CDIST_MAKE_VERSION=make -C "$(CDIST_DIR)" version CDIST_MAKE_HTML=make -C "$(CDIST_DIR)" html +CDIST_CONTRIB_MAKE_HTML=make -C "$(CDIST_CONTRIB_DIR)" html CDIST_CLEAN_HTML=make -C "$(CDIST_DOCS_DIR)/src" clean +CDIST_CONTRIB_CLEAN_HTML=make -C "$(CDIST_CONTRIB_DOCS_DIR)/src" clean SPHINXH=make -C $(WEBSITE_SRC_DIR) html SPHINXC=make -C $(WEBSITE_SRC_DIR) clean @@ -51,8 +56,14 @@ release-prepare: release-prepare-latest: release-prepare @grep '$(CDIST_CHANGELOG_VERSION)' "$(WEBSITE_MAN_PAGE)" || awk 'BEGIN { print_new = 0; } /All versions/ { print; print_new = 1; next; } print_new == 1 { print; print "* `$(CDIST_CHANGELOG_VERSION) `_"; print_new = 0; next; } { print; }' "$(WEBSITE_MAN_PAGE)" > "$(WEBSITE_MAN_PAGE)-new" && mv "$(WEBSITE_MAN_PAGE)-new" "$(WEBSITE_MAN_PAGE)" || exit 0 +# Build and import documentation from the cdist-contrib project. +sync-contrib: + $(CDIST_CONTRIB_MAKE_HTML) + mkdir -p "$(WEBSITE_MANUALS_DIR)/contrib/" + rsync -va "$(CDIST_CONTRIB_DOCS_HTML_DIST_DIR)/" "$(WEBSITE_MANUALS_DIR)/contrib/" + # Build website. -build: +build: sync-contrib $(SPHINXH) @cd "$(WEBSITE_HTML_DIST_DIR)/manual" && rm -f latest && ln -s "$(CDIST_CHANGELOG_VERSION)" latest @@ -76,4 +87,5 @@ release-publish-no-latest: release-no-latest publish clean: $(CDIST_CLEAN_HTML) + $(CDIST_CONTRIB_CLEAN_HTML) $(SPHINXC) diff --git a/src/_static/custom.css b/src/_static/custom.css index 2cc5aca8..81263c26 100644 --- a/src/_static/custom.css +++ b/src/_static/custom.css @@ -70,3 +70,8 @@ div.documentwrapper { font-size: 12px; } } + +/* Remove unwanted space between blocks. */ +div.section::after { + display: inline !important; +} diff --git a/src/cdist-changelog.rst b/src/cdist-changelog.rst index 8c94d24e..a53257f5 100644 --- a/src/cdist-changelog.rst +++ b/src/cdist-changelog.rst @@ -1,6 +1,23 @@ Changelog --------- +next: + * Explorer machine_type: Rewrite (Dennis Camera) + * New type: __sed (Ander Punnar) + * New type: __haproxy_dualstack (Evilham and ungleich) + * Type __apt_update_index: Fix complaint about suite change (Matthias Stecher) + * Type __package_update_index: Fix complaint about suite change (Matthias Stecher) + * Type __package_upgrade_all: Add new --apt-with-new-pkgs argument (Evilham) + * Type __apt_source: Fix complaint about suite change (Matthias Stecher) + * Type __package_apt: Fix complaint about suite change (Matthias Stecher) + * Type __debconf_set_selections: Fix bug where --file was unsupported (Evilham) + * Types __letsencrypt_cert, __grafana_dashboard: Improve bullseye support (Evilham) + * Type __ssh_authorized_key: Also remove tmpfile if removing line (Mark Verboom) + * Type __apt_pin: Add default priority, add comment in generated files (Daniel Fancsali) + * Type __file: make file uploading and attribute changes more atomic (Steven Armstrong) + * Type __dot_file: Add support for using --file parameter (Stephan Leemburg) + * Type __apt_ppa: Replace custom "remove-apt-repository" with add-apt-repository -r (Romain Dartigues) + 6.9.8: 2021-08-24 ~~~~~~~~~~~~~~~~~ * Type __rsync: Rewrite (Ander Punnar) diff --git a/src/cdist-documentation.rst b/src/cdist-documentation.rst index 6f0e2a07..8f46289f 100644 --- a/src/cdist-documentation.rst +++ b/src/cdist-documentation.rst @@ -1,11 +1,32 @@ Documentation ============= -.. toctree:: - :maxdepth: 1 +Manuals +~~~~~~~ - cdist-manual - cdist contrib types - cdist-os - cdist-speeches - cdist-changelog +* You will find an **introduction** as well as a **full reference** in the `latest + cdist manual `_. +* The community-maintained **'contrib' types** are documented on `their own + manual `_. +* Experimental features from the **beta** branch (i.e. cdist **trigger**, + **preos** and **scan**) are documented under the `beta manual + `_. +* Depending how you installed cdist, type manuals might also be availale via + the ``man`` command (e.g. ``man 7 cdist-type__file``). +* Manual for previous releases can be found on the `manual archives page + `_. + +Changelog +~~~~~~~~~ + +You will find the full changelog `here `_. + +Talks +~~~~~ + +* `2013-11-22_eth_linux_erfa `_ +* `2014-05-08_linuxtag_berlin `_ +* `2014-05-19_cdi.st-zkb_linux_erfa `_ +* `2014-06-10_openclouddays_teaser `_ +* `2014-11-07_sfs_linux_erfa_cdist_web_prototype `_ +* `2014-11-07_sfs_linux_erfa_cdist4 `_ diff --git a/src/cdist-features.rst b/src/cdist-features.rst index b0361d84..9698f7c8 100644 --- a/src/cdist-features.rst +++ b/src/cdist-features.rst @@ -1,7 +1,7 @@ Features ======== -But cdist ticks differently, here is the feature set that makes it unique. +Here are the features that make cdist unique. **Simplicity** There is only one type to extend cdist called **type** diff --git a/src/cdist-install.rst b/src/cdist-install.rst deleted file mode 100644 index f6f91bf9..00000000 --- a/src/cdist-install.rst +++ /dev/null @@ -1,167 +0,0 @@ -How to install cdist -==================== - -Requirements -------------- - -Source Host -~~~~~~~~~~~ - -This is the machine from which you will configure target hosts. - - * /bin/sh: A posix like shell (for instance bash, dash, zsh) - * Python >= 3.5 - * SSH client - * sphinx (for building html docs and/or the man pages) - -Target Hosts -~~~~~~~~~~~~ - - * /bin/sh: A posix like shell (for instance bash, dash, zsh) - * SSH server - -Install cdist -------------- - -From git -~~~~~~~~ - -Cloning cdist from git gives you the advantage of having -a version control in place for development of your own stuff -immediately. - -To install cdist, execute the following commands: - -.. code-block:: sh - - git clone https://code.ungleich.ch/ungleich-public/cdist.git - cd cdist - export PATH=$PATH:$(pwd -P)/bin - -From version 4.2.0 cdist tags and releases are signed. -You can get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_. -It is assumed that you are familiar with *git* ways of signing and verification. - -You can also get cdist from `github mirror `_. - -To install cdist with distutils from cloned repository, first you have to -create version.py: - -.. code-block:: sh - - ./bin/build-helper version - -Then, as usual, you execute the following command: - -.. code-block:: sh - - python setup.py install - - -Available versions in git -^^^^^^^^^^^^^^^^^^^^^^^^^ - - * The active development takes place in the **master** branch - * The released versions can be found in the tags - -Other branches may be available for features or bugfixes, but they -may vanish at any point. To select a specific branch use - -.. code-block:: sh - - # Generic code - git checkout -b origin/ - -So for instance if you want to use and stay with version 4.1, you can use - -.. code-block:: sh - - git checkout -b 4.1 origin/4.1 - -Building and using documentation (man and html) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you want to build and use the documentation, run: - -.. code-block:: sh - - make docs - -Documentation comes in two formats, man pages and full HTML -documentation. Documentation is built into distribution's -docs/dist directory. man pages are in docs/dist/man and -HTML documentation in docs/dist/html. - -If you want to use man pages, run: - -.. code-block:: sh - - export MANPATH=$MANPATH:$(pwd -P)/docs/dist/man - -Or you can move man pages from docs/dist/man directory to some -other directory and add it to MANPATH. - -Full HTML documentation can be accessed at docs/dist/html/index.html. - -You can also build only man pages or only html documentation, for -only man pages run: - -.. code-block:: sh - - make man - -for only html documentation run: - -.. code-block:: sh - - make html - -You can also build man pages for types in your ~/.cdist directory: - -.. code-block:: sh - - make dotman - -Built man pages are now in docs/dist/man directory. If you have -some other custom .cdist directory, e.g. /opt/cdist then use: - -.. code-block:: sh - - make DOT_CDIST_PATH=/opt/cdist dotman - -Note that `dotman`-target has to be built before a `make docs`-run, otherwise -the custom man-pages are not picked up. - -Python package -~~~~~~~~~~~~~~ - -Cdist is available as a python package at -`PyPi `_. You can install it using - -.. code-block:: sh - - pip install cdist - -Installing from source with signature verification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to install cdist from signed source and verify it, first you need to -download cdist archive and its detached signature. - -Get both, *cdist-x.y.z.tar.gz* and *cdist-x.y.z.tar.gz.asc* from release -notes of the desired tag *x.y.z* at -`cdist git repository `_. - -Get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_ -and import it into GPG. - -Now cdist source archive can be verified using `gpg`, e.g. to verify `cdist-6.2.0`: - -.. code-block:: sh - - $ gpg --verify cdist-6.2.0.tar.gz.asc cdist-6.2.0.targ.gz - gpg: Signature made Sat Nov 30 23:14:19 2019 CET - gpg: using RSA key 69767822F3ECC3C349C1EFFFEFD2AE4EC36B6901 - gpg: Good signature from "ungleich GmbH (ungleich FOSS) " [ultimate] - -Further steps are the same as for `installing from git `_. diff --git a/src/cdist-manual.rst b/src/cdist-manual-archives.rst similarity index 95% rename from src/cdist-manual.rst rename to src/cdist-manual-archives.rst index 3937c0f5..e316231f 100644 --- a/src/cdist-manual.rst +++ b/src/cdist-manual-archives.rst @@ -1,10 +1,5 @@ -cdist manual -============ - -* `Latest manual `_ - -* Checking out **beta** branch, i.e. cdist **trigger** and **preos** functionality? - Find the manual `here `_. +cdist manual archives +===================== **All versions** diff --git a/src/cdist-os.rst b/src/cdist-os.rst deleted file mode 100644 index a8e31226..00000000 --- a/src/cdist-os.rst +++ /dev/null @@ -1,19 +0,0 @@ -Supported operating systems -=========================== - -cdist was tested or is know to run on at least - -* `Alpine Linux `_ -* `Archlinux `_ -* `CentOS `_ -* `Debian `_ -* `Devuan `_ -* `Fedora `_ -* `FreeBSD `_ -* `Gentoo `_ -* `Mac OS X `_ -* `NetBSD `_ -* `OpenBSD `_ -* `Redhat `_ -* `Ubuntu `_ -* `XenServer `_ diff --git a/src/cdist-speeches.rst b/src/cdist-speeches.rst deleted file mode 100644 index 408249f7..00000000 --- a/src/cdist-speeches.rst +++ /dev/null @@ -1,9 +0,0 @@ -Speeches -======== - - * `2013-11-22_eth_linux_erfa `_ - * `2014-05-08_linuxtag_berlin `_ - * `2014-05-19_cdi.st-zkb_linux_erfa `_ - * `2014-06-10_openclouddays_teaser `_ - * `2014-11-07_sfs_linux_erfa_cdist_web_prototype `_ - * `2014-11-07_sfs_linux_erfa_cdist4 `_ diff --git a/src/cdist-support.rst b/src/cdist-support.rst deleted file mode 100644 index 2ebfd5b5..00000000 --- a/src/cdist-support.rst +++ /dev/null @@ -1,31 +0,0 @@ -Support -------- - -Chat -~~~~ -Matrix: ``#cdist:ungleich.ch`` - -IRC: ``#cdist`` @ `libera `_ - -Matrix and IRC are bridged. - - -Mailing list -~~~~~~~~~~~~ - -Bug reports, questions, patches, etc. should be send to the -`cdist mailing list `_. - -Linkedin -~~~~~~~~ - -If you have an account -at `Linked in `_, -you can join the -`cdist group `_. - -Commercial support -~~~~~~~~~~~~~~~~~~ - -You can request commercial support for cdist from -`ungleich `_. diff --git a/src/cdist-upgrade.rst b/src/cdist-upgrade.rst deleted file mode 100644 index 67fd4934..00000000 --- a/src/cdist-upgrade.rst +++ /dev/null @@ -1,188 +0,0 @@ -How to upgrade cdist -==================== - -Update the git installation ---------------------------- - -To upgrade cdist in the current branch use - -.. code-block:: sh - - git pull - - # Also update the manpages - make man - export MANPATH=$MANPATH:$(pwd -P)/doc/man - -If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break. -The master branch on the other hand is the development branch and may not be -working, break your setup or eat the tree in your garden. - -Safely upgrading to new versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To upgrade to **any** further cdist version, you can take the -following procedure to do a safe upgrade: - -.. code-block:: sh - - # Create new branch to try out the update - git checkout -b upgrade_cdist - - # Get latest cdist version in git database - git fetch -v - - # see what will happen on merge - replace - # master with the branch you plan to merge - git diff upgrade_cdist..origin/master - - # Merge the new version - git merge origin/master - -Now you can ensure all custom types work with the new version. -Assume that you need to go back to an older version during -the migration/update, you can do so as follows: - -.. code-block:: sh - - # commit changes - git commit -m ... - - # go back to original branch - git checkout master - -After that, you can go back and continue the upgrade: - -.. code-block:: sh - - # git checkout upgrade_cdist - - -Update the python package -------------------------- - -To upgrade to the lastet version do - -.. code-block:: sh - - pip install --upgrade cdist - -General update instructions ---------------------------- - -Updating from 3.0 to 3.1 -~~~~~~~~~~~~~~~~~~~~~~~~ - -The type **\_\_ssh_authorized_keys** now also manages existing keys, -not only the ones added by cdist. - -Updating from 2.3 to 3.0 -~~~~~~~~~~~~~~~~~~~~~~~~ - -The **changed** attribute of objects has been removed. -Use `messaging `_ instead. - -Updating from 2.2 to 2.3 -~~~~~~~~~~~~~~~~~~~~~~~~ - -No incompatibilities. - -Updating from 2.1 to 2.2 -~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting with 2.2, the syntax for requiring a singleton type changed: -Old format: - -.. code-block:: sh - - require="__singleton_type/singleton" ... - -New format: - -.. code-block:: sh - - require="__singleton_type" ... - -Internally the "singleton" object id was dropped to make life more easy. -You can probably fix your configuration by running the following code -snippet (currently untested, please report back if it works for you): - -.. code-block:: sh - - find ~/.cdist/* -type f -exec sed -i 's,/singleton,,' {} \; - -Updating from 2.0 to 2.1 -~~~~~~~~~~~~~~~~~~~~~~~~ - -Have a look at the update guide for [[2.0 to 2.1|2.0-to-2.1]]. - - * Type **\_\_package* and \_\_process** use --state **present** or **absent**. - The states **removed/installed** and **stopped/running** have been removed. - Support for the new states is already present in 2.0. - * Type **\_\_directory**: Parameter --parents and --recursive are now boolean - The old "yes/no" values need to be removed. - * Type **\_\_rvm_ruby**: Parameter --default is now boolean - The old "yes/no" values need to be removed. - * Type **\_\_rvm_gemset**: Parameter --default is now boolean - The old "yes/no" values need to be removed. - * Type **\_\_addifnosuchline** and **\_\_removeline** have been replaced by **\_\_line** - * The **conf** directory is now located at **cdist/conf**. - You need to migrate your types, explorers and manifests - manually to the new location. - * Replace the variable **\_\_self** by **\_\_object_name** - Support for the variable **\_\_object_name** is already present in 2.0. - * The types **\_\_autofs**, **\_\_autofs_map** and **\_\_autofs_reload** have been removed - (no maintainer, no users) - * Type **\_\_user**: Parameter --groups removed (use the new \_\_user_groups type) - * Type **\_\_ssh_authorized_key** has been replaced by more flexible type - **\_\_ssh_authorized_keys** - -Updating from 1.7 to 2.0 -~~~~~~~~~~~~~~~~~~~~~~~~ - -* Ensure python (>= 3.2) is installed on the source host -* Use "cdist config host" instead of "cdist-deploy-to host" -* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy" -* Use "cdist banner" for fun -* Use **\_\_object_name** instead of **\_\_self** in manifests - -Updating from 1.6 to 1.7 -~~~~~~~~~~~~~~~~~~~~~~~~ - -* If you used the global explorer **hardware_type**, you need to change - your code to use **machine** instead. - -Updating from 1.5 to 1.6 -~~~~~~~~~~~~~~~~~~~~~~~~ - -* If you used **\_\_package_apt --preseed**, you need to use the new - type **\_\_debconf_set_selections** instead. -* The **\_\_package** types accepted either --state deinstalled or - --state uninstaaled. Starting with 1.6, it was made consistently - to --state removed. - -Updating from 1.3 to 1.5 -~~~~~~~~~~~~~~~~~~~~~~~~ - -No incompatibilities. - -Updating from 1.2 to 1.3 -~~~~~~~~~~~~~~~~~~~~~~~~ - -Rename **gencode** of every type to **gencode-remote**. - -Updating from 1.1 to 1.2 -~~~~~~~~~~~~~~~~~~~~~~~~ - -No incompatibilities. - -Updating from 1.0 to 1.1 -~~~~~~~~~~~~~~~~~~~~~~~~ - -In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and -**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you -need to replace **\_\_file** calls in your manifests: - - * Remove --type from all \_\_file calls - * If type was symlink, use \_\_link and --type symbolic - * If type was directory, use \_\_directory diff --git a/src/cdist-why.rst b/src/cdist-why.rst index 1123a1de..945ed276 100644 --- a/src/cdist-why.rst +++ b/src/cdist-why.rst @@ -21,11 +21,11 @@ Not only is shell scripting widely known by system engineers, but it is also a very powerful language. Here are some features which make daily work easy: - * Configuration can react dynamicly on explored values - * High level string manipulation (using sed, awk, grep) - * Conditional support (**if, case**) - * Loop support (**for, while**) - * Support for dependencies between cdist types +* Configuration can react dynamicly on explored values +* High level string manipulation (using sed, awk, grep) +* Conditional support (**if, case**) +* Loop support (**for, while**) +* Support for dependencies between cdist types More than shell scripting ------------------------- diff --git a/src/conf.py b/src/conf.py index bf358070..9eef3878 100644 --- a/src/conf.py +++ b/src/conf.py @@ -47,7 +47,7 @@ master_doc = 'index' # General information about the project. project = 'cdist' -copyright = 'ungleich GmbH 2021' +copyright = 'ungleich GmbH 2022' # author = 'Darko Poljak' # The version info for the project you're documenting, acts as replacement for @@ -120,8 +120,8 @@ html_theme_options = { 'description': 'usable configuration management', 'github_button': 'false', 'extra_nav_links': { - 'Source code repository': 'https://code.ungleich.ch/ungleich-public/cdist', - 'ungleich Home': 'https://ungleich.ch', + 'source code repository': 'https://code.ungleich.ch/ungleich-public/cdist/', + 'ungleich homepage': 'https://ungleich.ch', }, 'show_powered_by': 'false', 'sidebar_width' : '300px', @@ -175,7 +175,7 @@ html_sidebars = { 'navigation.html', 'relations.html', 'searchbox.html', - 'donate.html', + 'donate.html' ] } diff --git a/src/index.rst b/src/index.rst index 816fe3a2..872b9eb6 100644 --- a/src/index.rst +++ b/src/index.rst @@ -1,12 +1,35 @@ cdist - usable configuration management ======================================= -cdist is a usable configuration management system. -It adheres to the KISS principle and -is being used in small up to enterprise grade environments. -It natively supports IPv6 since the first release. -cdist is an alternative to other configuration management systems. +cdist is a mature configuration management system that adheres to the KISS +principle. It has been used in small up to enterprise grade environment for +years and effectively is an alternative to other configuration management +system such as `Ansible `_, `Chef +`_ or `Puppet `_. +Community +~~~~~~~~~ + +You are welcome to drop by and ask questions on the `#cdist:ungleich.ch +`_ matrix room or ``#cdist`` IRC +channel on `libera `_. The Matrix room and IRC channel +are bridged via a simple relay bot. + +Development +~~~~~~~~~~~ + +Source code repositories and issue trackers can be found on ungleich's software +forge: + +* `ungleich-public/cdist `_: core cdist logic and types. +* `ungleich-public/cdist-contrib `_: extra useful types not released as part of core cdist. +* `ungleich-public/cdist-web `_: sources of this website. + +Commercial support +~~~~~~~~~~~~~~~~~~ + +You can request commercial support for cdist from +`ungleich `_. .. toctree:: :maxdepth: 3 @@ -16,6 +39,3 @@ cdist is an alternative to other configuration management systems. cdist-why cdist-features cdist-documentation - cdist-install - cdist-upgrade - cdist-support -- 2.40.1