{"id":20663623,"url":"https://github.com/networkupstools/nut-website","last_synced_at":"2025-04-19T15:55:27.470Z","repository":{"id":14166525,"uuid":"16872530","full_name":"networkupstools/nut-website","owner":"networkupstools","description":"Network UPS Tools website and protocol library","archived":false,"fork":false,"pushed_at":"2025-04-09T23:59:41.000Z","size":65607,"stargazers_count":7,"open_issues_count":13,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-10T00:32:39.970Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tmknom/study-vagrant","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/networkupstools.png","metadata":{"files":{"readme":"README.asciidoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-02-15T21:47:02.000Z","updated_at":"2025-04-09T23:59:44.000Z","dependencies_parsed_at":"2023-10-24T12:33:29.287Z","dependency_job_id":"5f4c32e7-d0b4-4dd3-b2c6-a9ab8729ce7c","html_url":"https://github.com/networkupstools/nut-website","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-website","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-website/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-website/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-website/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/networkupstools","download_url":"https://codeload.github.com/networkupstools/nut-website/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249731218,"owners_count":21317341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T19:18:59.942Z","updated_at":"2025-04-19T15:55:27.436Z","avatar_url":"https://github.com/networkupstools.png","language":"Python","readme":"Network UPS Tools website\n=========================\n\nThis repository contains the scripts needed to generate the\nlink:https://www.networkupstools.org[NUT website].\n\nSince it was originally part of the\nlink:https://github.com/networkupstools/nut/[NUT source tree],\nit shares some history, and you can save some bandwidth if you\nalready have a copy of the NUT repository downloaded:\n\n----\n:; git clone --reference /path/to/nut \\\n    https://github.com/networkupstools/nut-website.git\n----\n\nOnce you have cloned the nut-website repository, you can initialize the\nsubmodules, and pull your copy of NUT into the website tree as well:\n\n----\n:; git submodule init\nSubmodule 'ddl' (https://github.com/networkupstools/nut-ddl.git) registered for path 'ddl'\nSubmodule 'nut' (https://github.com/networkupstools/nut.git) registered for path 'nut'\n:; git submodule update --reference /path/to/nut nut\n...\n----\n\nRequired Packages\n-----------------\n\nYou will need a copy of `AsciiDoc` toolkit, `a2x` (part of AsciiDoc), and\nits dependencies for MAN, HTML and PDF document formats generation (including\n`dblatex`, `xmllint`, and `xsltproc`). Current version requirements will be\nlisted in the output of the `./configure` script. To build the Hardware\nCompatibility List (HCL) page, you will need either the `simplejson` or `json`\nPython module (the json module that comes with Python 2.7 will work) and the\n`lxml` module. You will also need `autoconf` and `automake`, and possibly\n`libtool` since the NUT module uses it.\n\n[NOTE]\n======\nWith recent Ubuntu/Debian releases, Python2 is deprecated so much that `pip2`\ntool seems to be no longer packaged. If you have both `python2` and `python3`\ninstalled, you may have install modules by `pip3` or APT and to either declare\nthe preference via environment variables for NUT and NUT-Website `configure`\nand other scripts, or change system-wide default symlink to `python` once:\n\n----\n:; sudo apt-get install python3-pip\n:; python3 -m pip install lxml simplejson pycparser pathlib\n\n### Note: Newer Python releases can suggest to use APT packages for modules\n### too (note also that \"pathlib\" may be not available this way, and may be\n### in fact part of the base Python distribution); in this case:\n:; sudo apt-get install python3-{lxml,simplejson,pycparser}\n----\n\nand then either system-wide:\n----\n:; sudo apt-get install python-is-python3\n----\n\nor constrain the preference to nut-website builds:\n----\n:; PYTHON='/usr/bin/env python3' ./ci_build.sh\n----\n======\n\nThe `source-highlight` package is optional, but if available, will be used by\nAsciiDoc for syntax highlighting of examples.\n\nThe optional `htmlproofer` tool from https://github.com/gjtorikian/html-proofer\nproject can be used to sanity-check links and similar aspects of the markup in\ngenerated HTML pages. On Debian/Ubuntu systems you can install it as a package:\n\n----\n:; sudo apt-get install ruby-html-proofer\n----\n\n[NOTE]\n======\nIf your `htmlproofer` runs complain like this:\n\n----\nhtmlproofer 3.19.2 | Error:  \"\\xC3\" on US-ASCII\n  /usr/lib/.../nokogiri/html5.rb:389:in `encode': \"\\\\xC3\" on US-ASCII (Encoding::InvalidByteSequenceError)\n----\n\nTry exporting `LANG` and `LC_ALL` environment variables to use UTF-8 capable\nlocales (already handled in the `Makefile.am` targets by `HTMLPROOFER_ENV`);\nthis may further require installing some or all locale packages, e.g.:\n\n----\n:; sudo apt-get install locales-all\n----\n======\n\nGNU `make` and GNU `coreutils` are recommended, but if you see any remaining\nnon-portable constructs in the Makefiles, please let us know.\n\nBuilding\n--------\n\nEditing the Makefile.am source\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWARNING: Due to lines which `# HIDE FROM AUTOMAKE #` some GNU syntax which\nconflicts with automake syntax, you *MUST* use `autogen.sh` to re-generate\nthe practical `Makefile` during development cycles. If you rely on automatic\ntypical regeneration of `Makefile.am` -\u003e `Makefile.in` -\u003e `Makefile`, the\nresulting file can have crucial parts commented away.\n\nAlternately, `make unhide-from-automake` after edits, e.g. to fiddle with\nspell checker Makefile recipes for historic releases:\n\n----\n:; make unhide-from-automake ; make spellcheck NUT_SPELL_DICT=nut-website.dict\n----\n\nQuick builds for CI and developer iterations\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nMain rituals for re-builds should now be handled well by a single script:\n\n----\n:; ./ci_build.sh\n----\n\nFor maintainers (or CI agents) who may push the web-site codebase, further\nenvvars may be useful to commit changes locally, and to push index upwards:\n\n----\n# To publish automatically use:\n:;   export CI_AUTOCOMMIT=true\n:;   export CI_AUTOPUSH=true\n\n# Optionally (on CI) to avoid rebuilds in cases when Git sources did not\n# change after a pull of all nut-website and submodule HEADs (returns exit\n# code \"42\" then, to be handled by the caller):\n:;   export CI_AVOID_RESPIN=true\n\n# Optionally - for the rare historic-release sub-sites (by NUT tag), e.g.:\n:;   export NUT_HISTORIC_RELEASE=v2.7.4\n----\n\nAlso, to make sure that syntax of `nut-ddl` data dump files is not ambiguous,\nyou can tell their parser to abort in case of doubts:\n\n----\n:;   export NUT_DDL_PEDANTIC_DECLARATIONS=True\n\n:; ... make ...\nTraceback (most recent call last):\n  File \"/home/jim/nut-website/./tools/nut-ddl.py\", line 1532, in \u003cmodule\u003e\n    commentsMap[pattern](comment)\n  File \"/home/jim/nut-website/./tools/nut-ddl.py\", line 400, in nds_dev_comment_block\n    raise RuntimeWarning (msg)\nRuntimeWarning: Invalid device block comment: does not end with DEVICE:EOC (blank non-comment lines mid-block?)\nmake: *** [Makefile:1012: ddl/PowerWalker/PowerWalker__VI_2200_SH__usbhid-ups__2.7.4__01.dev.txt] Error 1\n----\n\n\nManual building in detail\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\n----\n:; ./autogen.sh \u0026\u0026 ./configure \u0026\u0026 { make -k ; make ; }\n----\n\nNOTE: There are currently some issues with parallel builds (e.g. `protocols`\nsub-directory should be built before `OUTDIR` but target dependencies do not\nsay so). Please run `make` sequentially for the time being.\n\nThe root of the website will be in the `output/` directory, if all goes well.\n\nBuilding release-version sites\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nEvery once in a while NUT has releases :) and those end up packaged in many\noperating system distributions or equivalent bundles of binary code, and are\nused by the majority of NUT users.\n\nWhile the main nut-website now aims to follow the active development based on\ncurrent \"master\" or \"main\" branches of the components involved, we also publish\nreference sub-sites with static data (man pages, configuration, compatibility\ninformation, etc.) for those people to see about setting up their practical\nsystems properly. Such pages are marked with a note on top that they represent\nan old and immutable codebase which may differ from modern project state.\n\nThis also impacts some but not all pages of the nut-website as well -- e.g.\nthe `stable-hcl.txt` file which is a wrapper to include `nut/data/driver.list`\ninfo, but not all of the main website files currently (just because it is too\ncumbersome to partially check out arbitrary old codebase to build with current\nupdated recipes). Likewise, general markup and footers, etc. remain from the\ncurrent nut-website codebase at the time of (re-)generation.\n\nIn particular, the NUT DDL pertains to all NUT releases (reports the tested\nrelease in the filenames) so is not published separately per historic release.\n\nNormally this should be done once per release, with a call like this:\n\n----\n:; export NUT_HISTORIC_RELEASE=v2.7.4\n:; ./autogen.sh \u0026\u0026 \\\n    ./configure --with-NUT_HISTORIC_RELEASE=${NUT_HISTORIC_RELEASE} \u0026\u0026 \\\n    { make -k dist-sig-files || make dist-files; } \u0026\u0026 \\\n    { make -k ; make; }\n----\n\nWhich would populate e.g. `output/historic/v2.7.4` subdirectory that would be\ncopied and committed into same-named path under `networkupstools.github.io` as\ndetailed below. Generation of the main nut-website would also populate an index\nfile of the \"historic\" subdirectory, based on `historic/index.txt` contents,\nto refer to such officially published snapshots. This index is currently\nmaintained manually, to ensure human decision about publishing (or hiding) an\nhistoric release (especially a release candidate) vs. experimenting with that.\n\nNOTE: `make dist-files` should update the historic release site source tarballs\nand related ChangeLog, news and checksum files IFF the release data was not yet\nthere. You probably need to commit that back to \"source\" github repository.\n\nNOTE: For hardcore maintainers, there should be a PGP/GPG key to also sign the\nrelease tarball, calling `make dist-sig-files` (would fail without a key).\n\nSanity-checking the generated HTML files\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf the `htmlproofer` tool is installed (see above) and detected by the\n`configure` script (automatically for presence in `PATH`), you can explicitly\ncall `make check-htmlproofer` to validate the files present in `OUTDIR_BASE`\nand/or `OUTDIR` (if stored separately from the base for custom or historic\nwebsite builds).\n\nYou can also validate the published website repository (into which you would\nupload the generated `OUTDIR` contents) as e.g. prepared by the `ci_build.sh`\nusing `make check-htmlproofer-OUTDIR_PUBLISHED` (optionally customize the\n`OUTDIR_PUBLISHED` environment or `make` variable to point to the checkout\nlocation for that repository, if not using the scripted default).\n\nNote that this check can take about 10 minutes (especially if not disabling\nthe referenced external site availability), so it is not done by default.\nYou can pass custom `HTMLPROOFER_OPTIONS` to the `make` operation, if desired;\nconsider pasting the `HTMLPROOFER_OPTIONS_URLSWAP` in that case.\n\nPublishing\n----------\n\nNOTE: These are internal notes for the maintainers.\n\nThe build result is published to the\nhttps://github.com/networkupstools/networkupstools-master.github.io[NUT\ngithub.io master site repository]\nas well as news maintenance on\nhttps://github.com/networkupstools/networkupstools.github.io[NUT\ngithub.io latest-release site repository]\n\nHence, the rolling master site publication is as easy as:\n\n----\n:; git clone https://github.com/networkupstools/networkupstools-master.github.io\n:; rsync -avPHK ./output/* /path/to/networkupstools-master.github.io/\n----\n\nRelease site publication is much less frequent. It follows the master\nsite guideline when making a release, but only requires updating the\n`index.html` file when `news.txt` is updated, as noted below.\n\nNOTE: Be careful to use `git mergetool -y` to merge the updates from\na newly generated `index.html` into the release site, to keep intact\nthe title (marked with comments) which specifies the type of site.\n\n----\n:; git clone https://github.com/networkupstools/networkupstools.github.io\n:; cp -R ./output/index.html /path/to/networkupstools.github.io/\n:; (cd /path/to/networkupstools.github.io/ \u0026\u0026 git difftool -y)\n----\n\nNOTE: Maybe also update the `ddl` and `stable-hcl.html` on master site,\nas its updates often reflect newly confirmed support of devices by\nexisting NUT releases.\n\nUpdates\n-------\n\nIf you only have a small patch (fixing a typo or wording), don't feel\nobliged to install all of the dependencies listed above just to test it.\nFeel free to create a pull request on this repository, or (less preferable\nas slower to process) send the patch as an attachment to the\nlink:https://www.networkupstools.org/support.html#_mailing_lists[nut-upsdev list].\n\nMaintainer note: Publishing became part of NUT CI farm automation in 2022,\nso whenever master branch sources of relevant repositories are changed,\nthe website should not lag behind too long. Needed behavior is defined in\nthis repository in `Jenkinsfile-infra` file, with job history visible at\nhttps://ci.networkupstools.org/view/InfraTasks/job/nut-website/\n\n* As of this writing, changes of `nut-website` repository should get picked\n  up quickly thanks to \"web hooks\" sent by GitHub to NUT CI farm servers,\n  and changes in NUT, NUT-DDL and other repositories involved would be\n  evaluated every 3 hours.\n\n* (Re-)builds of historic sub-sites for release candidates etc. are handled\n  manually by maintainers, to publish source tarballs as well (in nut-source\n  repository, in the web-site, in GitHub releases page), and generally happen\n  once per such release with a spell like this:\n+\n------\n:; CI_AUTOCOMMIT=true CI_AUTOPUSH=true NUT_HISTORIC_RELEASE=v2.8.0-rc3 ./ci_build.sh\n------\n\n* The `nut-website` specific spell-checking is handled with a dynamic mix of\n  original `nut/docs/nut.dict` and custom `nut-website.dict.addon` with key\n  words specific to files in the website (including HTML and asciidoc markup).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut-website","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetworkupstools%2Fnut-website","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut-website/lists"}