Bug #5902
closedmanuals only built for "master" and published in a folder "latest"
Added by laforge about 1 year ago. Updated about 1 year ago.
100%
Description
We initially started to put nightly builds of the osmo-* user manuals at https://ftp.osmocom.org/docs/latest/
Then we started to have "latest" debian packages which actually are the latest tagged releases, and not the "nightly" builds.
This is confusing, but probably hard to resolve by now.
What's even more strange is that we don't have builds of user manuals for the last tagged versions, or even for any earlier tagged versions.
Ideally we would build the user manuals for every tag in the repo, and have the PDF renderings for that version available somewhere on {ftp,downloads}.osmocom.org
There's of course a risk that some ancient release will fial to build its manual on a modern debian, but I guess we can deal with that by explicitly blacklisting "known broken" tags.
Checklist
- osmo-gsm-manuals: Change upload path to project/master/: write patch
- osmo-gsm-manuals: Change upload path to project/master/: merge
- pysim: adjust to publish manuals to project/master
- wait until all manuals were published to new directory structure
- set up nginx redirects for all existing manuals
- delete the "latest" directory
- generate manuals for previous releases: write script & jenkins job
Updated by osmith about 1 year ago
I would go with this directory structure:
docs/
osmo-hlr/
master/
osmohlr-usermanual.pdf
osmohlr-vty-reference.pdf
1.6.1/
osmohlr-usermanual.pdf
osmohlr-vty-reference.pdf
And for docs/latest, I'd suggest making redirects in the nginx config so e.g. docs/latest/osmohlr-usermanual.pdf points to docs/osmo-hlr/master/osmohlr-usermanual.pdf. Then delete the latest directory.
EDIT: docs/latest could also be redirected to docs, in case somebody has that as bookmark.
Updated by neels about 1 year ago
And for docs/latest, I'd suggest making redirects in the nginx config so e.g. docs/latest/osmohlr-usermanual.pdf points to docs/osmo-hlr/master/osmohlr-usermanual.pdf. Then delete the latest directory.
makes sense for "backwards compat", but from the naming, "latest" should rather point to the latest release?
Updated by laforge about 1 year ago
On Fri, Mar 03, 2023 at 12:43:27AM +0000, neels wrote:
Issue #5902 has been updated by neels.
And for docs/latest, I'd suggest making redirects in the nginx config so e.g. docs/latest/osmohlr-usermanual.pdf points to docs/osmo-hlr/master/osmohlr-usermanual.pdf. Then delete the latest directory.
makes sense for "backwards compat", but from the naming, "latest" should rather point to the latest release?
Now I'm confused. This ticket exists to create a backwars-compatible work-around for the situation we've had
form any years:
We initially started to put nightly builds of the osmo-* user manuals at https://ftp.osmocom.org/docs/latest/
Then we started to have "latest" debian packages which actually are the latest tagged releases, and not the "nightly" builds.
So how is your comment improving the situation, other than stating "we should break compatibility and not
bother at all with people following old links?
Updated by osmith about 1 year ago
- Checklist item osmo-gsm-manuals: Change upload path to project/master/: write patch added
- Checklist item osmo-gsm-manuals: Change upload path to project/master/: merge added
- Checklist item pysim: adjust to publish manuals to project/master added
- Checklist item wait until all manuals were published to new directory structure added
- Checklist item set up nginx redirects for all existing manuals added
- Checklist item delete the "latest" directory added
- Checklist item generate manuals for previous releases: write script & jenkins job added
- Status changed from New to In Progress
- % Done changed from 0 to 30
Neels, FYI the "latest" name would not be visible anymore in the directory listing or in the URL. There would only be redirects from latest to master, the same file that the user would get with the previous URL.
First patch to publish manuals to $project/master from now on:
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/31688/1
Updated by osmith about 1 year ago
- Checklist item osmo-gsm-manuals: Change upload path to project/master/: merge set to Done
- Checklist item pysim: adjust to publish manuals to project/master set to Done
pysim html docs: https://gerrit.osmocom.org/c/pysim/+/31718
Updated by osmith about 1 year ago
- Checklist item wait until all manuals were published to new directory structure set to Done
- % Done changed from 30 to 40
laforge: here are the redirect rules (untested), can you apply them to nginx config of the server and assign the issue back to me?
#
# Rewrite rules for docs/latest (OS#5902)
#
rewrite ^/docs/latest$ /docs/ permanent;
# osmo-bsc
rewrite ^/docs/latest/osmobsc-(.*)$ /docs/osmo-bsc/master/osmobsc-$1 permanent;
rewrite ^/docs/latest/aoip-mgw-options.pdf$ /docs/osmo-bsc/master/aoip-mgw-options.pdf permanent;
rewrite ^/docs/latest/osmux-reference.pdf$ /docs/osmo-bsc/master/osmux-reference.pdf permanent;
# osmo-bsc-nat
rewrite ^/docs/latest/osmobscnat-(.*)$ /docs/osmo-bsc-nat/master/osmobscnat-$1 permanent;
# osmo-bts
rewrite ^/docs/latest/osmobts-(.*)$ /docs/osmo-bts/master/osmobts-$1 permanent;
rewrite ^/docs/latest/rtp-amr.pdf$ /docs/osmo-bts/master/rtp-amr.pdf permanent;
# osmo-cbc
rewrite ^/docs/latest/osmocbc-(.*)$ /docs/osmo-cbc/master/osmocbc-$1 permanent;
# osmo-e1d
rewrite ^/docs/latest/osmoe1d-(.*)$ /docs/osmo-e1d/master/osmoe1d-$1 permanent;
# osmo-e1-hardware
rewrite ^/docs/latest/e1-tracer-usermanual.pdf$ /docs/osmo-e1-hardware/master/e1-tracer-usermanual.pdf permanent;
rewrite ^/docs/latest/icE1usb-usermanual.pdf$ /docs/osmo-e1-hardware/master/icE1usb-usermanual.pdf permanent;
# osmo-gbproxy
rewrite ^/docs/latest/osmogbproxy-(.*)$ /docs/osmo-gbproxy/master/osmogbproxy-$1 permanent;
# osmo-ggsn
rewrite ^/docs/latest/osmoggsn-(.*)$ /docs/osmo-ggsn/master/osmoggsn-$1 permanent;
# osmo-gsm-tester
rewrite ^/docs/latest/osmo-ggsn-tester-(.*)$ /docs/osmo-gsm-tester/master/osmo-ggsn-tester-$1 permanent;
# osmo-hlr
rewrite ^/docs/latest/osmohlr-(.*)$ /docs/osmo-hlr/master/osmohlr-$1 permanent;
# osmo-hnbgw
rewrite ^/docs/latest/osmohnbgw-(.*)$ /docs/osmo-hnbgw/master/osmohnbgw-$1 permanent;
# osmo-hnodeb
rewrite ^/docs/latest/osmohnodeb-(.*)$ /docs/osmo-hnodeb/master/osmohnodeb-$1 permanent;
# osmo-mgw
rewrite ^/docs/latest/osmomgw-(.*)$ /docs/osmo-mgw/master/osmomgw-$1 permanent;
# osmo-msc
rewrite ^/docs/latest/osmomsc-(.*)$ /docs/osmo-msc/master/osmomsc-$1 permanent;
# osmo-pcap
rewrite ^/docs/latest/osmopcap-(.*)$ /docs/osmo-pcap/master/osmopcap-$1 permanent;
rewrite ^/docs/latest/osmo-pcap-(.*)$ /docs/osmo-pcap/master/osmo-pcap-$1 permanent;
# osmo-pcu
rewrite ^/docs/latest/osmopcu-(.*)$ /docs/osmo-pcu/master/osmopcu-$1 permanent;
# osmo-remsim
rewrite ^/docs/latest/osmoremsim-(.*)$ /docs/osmo-remsim/master/osmoremsim-$1 permanent;
# osmo-sgsn
rewrite ^/docs/latest/osmosgsn-(.*)$ /docs/osmo-sgsn/master/osmosgsn-$1 permanent;
# osmo-sip-connector
rewrite ^/docs/latest/osmosipconnector-(.*)$ /docs/osmo-sip-connector/master/osmosipconnector-$1 permanent;
# osmo-smlc
rewrite ^/docs/latest/osmosmlc-(.*)$ /docs/osmo-smlc/master/osmosmlc-$1 permanent;
# osmo-stp
rewrite ^/docs/latest/osmostp-(.*)$ /docs/osmo-stp/master/osmostp-$1 permanent;
# osmo-trx
rewrite ^/docs/latest/osmotrx-(.*)$ /docs/osmo-trx/master/osmotrx-$1 permanent;
# osmo-upf
rewrite ^/docs/latest/osmoupf-(.*)$ /docs/osmo-upf/master/osmoupf-$1 permanent;
# osmocom-bb
rewrite ^/docs/latest/osmocombb-(.*)$ /docs/osmocom-bb/master/osmocombb-$1 permanent;
# openbsc
rewrite ^/docs/latest/osmo-bsc-(.*)$ /docs/openbsc/master/osmo-bsc-$1 permanent;
rewrite ^/docs/latest/osmonitb-(.*)$ /docs/openbsc/master/osmonitb-$1 permanent;
# pysim
rewrite ^/docs/latest/osmopysim-(.*)$ /docs/pysim/master/osmopysim-$1 permanent;
rewrite ^/docs/latest/pysim/(.*)$ /docs/pysim/master/html/$1 permanent;
Updated by laforge about 1 year ago
- Assignee changed from laforge to osmith
It's not nginx (as it doesn't have anyway nearly as sophisticated directory indexing as we want, with sort-by-date), but lighttpd.
I've added your ssh key for root@2a01:4f8:201:344a::1:2 so you can change the configs of the system-installed (debian) lighttpd in /etc/lighttpd/
There's an etckeeper so you can keep track of modifications and/or revert back.
Updated by osmith about 1 year ago
- Checklist item set up nginx redirects for all existing manuals set to Done
- Checklist item delete the "latest" directory set to Done
- % Done changed from 40 to 60
laforge wrote in #note-8:
It's not nginx (as it doesn't have anyway nearly as sophisticated directory indexing as we want, with sort-by-date), but lighttpd.
I've added your ssh key for root@2a01:4f8:201:344a::1:2 so you can change the configs of the system-installed (debian) lighttpd in /etc/lighttpd/
There's an etckeeper so you can keep track of modifications and/or revert back.
Done.
lighttpd configlighttpd config
# Redirects for legacy /docs/latest urls (OS#5902) url.redirect = ( "^/docs/latest/$" => "/docs/", # osmo-bsc "^/docs/latest/osmobsc-(.*)$" => "/docs/osmo-bsc/master/osmobsc-$1", "^/docs/latest/aoip-mgw-options.pdf$" => "/docs/osmo-bsc/master/aoip-mgw-options.pdf", "^/docs/latest/osmux-reference.pdf$" => "/docs/osmo-bsc/master/osmux-reference.pdf", # osmo-bsc-nat "^/docs/latest/osmobscnat-(.*)$" => "/docs/osmo-bsc-nat/master/osmobscnat-$1", # osmo-bts "^/docs/latest/osmobts-(.*)$" => "/docs/osmo-bts/master/osmobts-$1", "^/docs/latest/rtp-amr.pdf$" => "/docs/osmo-bts/master/rtp-amr.pdf", # osmo-cbc "^/docs/latest/osmocbc-(.*)$" => "/docs/osmo-cbc/master/osmocbc-$1", # osmo-e1d "^/docs/latest/osmoe1d-(.*)$" => "/docs/osmo-e1d/master/osmoe1d-$1", # osmo-e1-hardware "^/docs/latest/e1-tracer-usermanual.pdf$" => "/docs/osmo-e1-hardware/master/e1-tracer-usermanual.pdf", "^/docs/latest/icE1usb-usermanual.pdf$" => "/docs/osmo-e1-hardware/master/icE1usb-usermanual.pdf", # osmo-gbproxy "^/docs/latest/osmogbproxy-(.*)$" => "/docs/osmo-gbproxy/master/osmogbproxy-$1", # osmo-ggsn "^/docs/latest/osmoggsn-(.*)$" => "/docs/osmo-ggsn/master/osmoggsn-$1", # osmo-gsm-tester "^/docs/latest/osmo-gsm-tester-(.*)$" => "/docs/osmo-gsm-tester/master/osmo-gsm-tester-$1", # osmo-hlr "^/docs/latest/osmohlr-(.*)$" => "/docs/osmo-hlr/master/osmohlr-$1", # osmo-hnbgw "^/docs/latest/osmohnbgw-(.*)$" => "/docs/osmo-hnbgw/master/osmohnbgw-$1", # osmo-hnodeb "^/docs/latest/osmohnodeb-(.*)$" => "/docs/osmo-hnodeb/master/osmohnodeb-$1", # osmo-mgw "^/docs/latest/osmomgw-(.*)$" => "/docs/osmo-mgw/master/osmomgw-$1", # osmo-msc "^/docs/latest/osmomsc-(.*)$" => "/docs/osmo-msc/master/osmomsc-$1", # osmo-pcap "^/docs/latest/osmopcap-(.*)$" => "/docs/osmo-pcap/master/osmopcap-$1", "^/docs/latest/osmo-pcap-(.*)$" => "/docs/osmo-pcap/master/osmo-pcap-$1", # osmo-pcu "^/docs/latest/osmopcu-(.*)$" => "/docs/osmo-pcu/master/osmopcu-$1", # osmo-remsim "^/docs/latest/osmo-remsim-(.*)$" => "/docs/osmo-remsim/master/osmo-remsim-$1", # osmo-sgsn "^/docs/latest/osmosgsn-(.*)$" => "/docs/osmo-sgsn/master/osmosgsn-$1", # osmo-sip-connector "^/docs/latest/osmosipconnector-(.*)$" => "/docs/osmo-sip-connector/master/osmosipconnector-$1", # osmo-smlc "^/docs/latest/osmosmlc-(.*)$" => "/docs/osmo-smlc/master/osmosmlc-$1", # osmo-stp "^/docs/latest/osmostp-(.*)$" => "/docs/osmo-stp/master/osmostp-$1", # osmo-trx "^/docs/latest/osmotrx-(.*)$" => "/docs/osmo-trx/master/osmotrx-$1", # osmo-upf "^/docs/latest/osmoupf-(.*)$" => "/docs/osmo-upf/master/osmoupf-$1", # osmocom-bb "^/docs/latest/osmocombb-(.*)$" => "/docs/osmocom-bb/master/osmocombb-$1", # openbsc "^/docs/latest/osmo-bsc-(.*)$" => "/docs/openbsc/master/osmo-bsc-$1", "^/docs/latest/osmonitb-(.*)$" => "/docs/openbsc/master/osmonitb-$1", # pysim "^/docs/latest/osmopysim-(.*)$" => "/docs/pysim/master/osmopysim-$1", "^/docs/latest/pysim/(.*)$" => "/docs/pysim/master/html/$1", )
Updated by osmith about 1 year ago
- Checklist item generate manuals for previous releases: write script & jenkins job set to Done
- % Done changed from 60 to 90
Manuals for previous releases generated:
https://downloads.osmocom.org/docs/
Script and jenkins job:
https://gerrit.osmocom.org/c/osmo-ci/+/32016
Updated by osmith about 1 year ago
- Status changed from In Progress to Resolved
- % Done changed from 90 to 100
