Feature #3036
closedupdate vty reference -- and make it so that it can be done without manual edits
100%
Description
osmo-bts has a number of variants: osmo-bts-trx, osmo-bts-sysmo, etc., and each may have some differing VTY commands.
The way we currently generate the vty reference PDF in osmo-gsm-manuals is that we launch the program and issue 'show online-help' on the vty; this outputs an XML of all VTY commands and their docs.
But how do we produce one VTY reference for all of the various BTS types?
Should we change osmo-gsm-manuals to produce N different VTY references, one for each BTS model?
Should we somehow combine all generated XMLs?
Decide on the above, generate the VTY reference for each BTS model and update osmo-gsm-manuals.git with it.
Furthermore, osmo-bts-* usually exits right away when there is no BSC to connect to. That's a bit cumbersome when all you want to do is generate the VTY reference XML. Maybe we can introduce a cmdline switch to generate the XML instead of going through the VTY?
Updated by laforge about 6 years ago
- Assignee set to neels
I think it's easiest to have separate reference manuals, one for each of the osmo-bts-* programs. This sticks with our existing tools, processes and the notion that we run one program and generat the vty reference for that program.
regarding osmo-bts exiting: it may be time to finally change that? This was a very early "fail fast" hack in 2011 or so.
Updated by neels about 6 years ago
laforge wrote:
I think it's easiest to have separate reference manuals, one for each of the osmo-bts-* programs. This sticks with our existing tools, processes and the notion that we run one program and generat the vty reference for that program.
ack
regarding osmo-bts exiting: it may be time to finally change that? This was a very early "fail fast" hack in 2011 or so.
(wrong issue? --> #3011?)
Updated by neels over 3 years ago
libosmocore now has this patch [1] which allows client programs to dump the XML reference to stdout directly.
At least some osmo-programs support that by the --vty-ref-xml cmdline option: dump the reference and exit
[1] https://git.osmocom.org/libosmocore/commit/?id=cf70aa0c40c574c32b832454f725cc37459c5d8d
"enable vty xml dumping to stdout"
see also
https://git.osmocom.org/osmo-bsc/commit/?id=10983f206ba2d58424bd829c73ebc1ac7e9e7c0b
Generating separate manuals for each BTS model is not addressed yet.
Updated by fixeria over 3 years ago
- Status changed from New to In Progress
- Assignee changed from neels to fixeria
- Priority changed from Normal to High
Oh, I didn't know that we have a ticket for this problem. Nice!
Should we change osmo-gsm-manuals to produce N different VTY references, one for each BTS model?
Yep, this sounds like the most reasonable approach. Generating a single file with all model specific options would be better, but more complicated.
I am actually already working on it as a part of SYS#4937. Will submit the patches soon.
Updated by fixeria over 3 years ago
- % Done changed from 0 to 80
After several days of hard work, I am finally getting the first results: *.pdf files are generated separately for all BTS models.
Here are changes for osmo-gsm-manuals:
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/20950 Makefile.docbook.inc: fix incorrect variable name in documentation
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/20951 Makefile.vty-reference.inc: create 'generated' in this file
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/20952 vty_reference_combine.sh: print the final result to stdout
and for osmo-bts-trx:
https://gerrit.osmocom.org/c/osmo-bts/+/20956 doc/manuals: generate XML VTY reference at build-time
https://gerrit.osmocom.org/c/osmo-bts/+/20953 main: do not print asciiart to stdout, remove that printf()
https://gerrit.osmocom.org/c/osmo-bts/+/20954 main: register VTY commands before handle_options()
https://gerrit.osmocom.org/c/osmo-bts/+/20955 osmo-bts-lc15: use consistent name for containing directory
However, the generated *.pdf files still lack documentation for model-specific VTY options. The problem is that those options are registered when 'struct gsm_bts' is allocated (!), and not when the program starts. What's even worse, some commands depend on a global pointer to 'struct gsm_bts'. This needs to be reworked.
Updated by fixeria over 3 years ago
- Status changed from In Progress to Feedback
- % Done changed from 80 to 100
I've finally managed to get the model specific options appear in the XML VTY reference:
https://gerrit.osmocom.org/c/osmo-bts/+/20954 main: register VTY commands before handle_options()
https://gerrit.osmocom.org/c/osmo-bts/+/21010 main: move general options from bts_vty_init()
https://gerrit.osmocom.org/c/osmo-bts/+/21011 vty: call bts_model_vty_init() from bts_vty_init()
All changes are submitted for review, once merged - we can close this ticket.
Updated by fixeria over 3 years ago
- Status changed from Feedback to Resolved
All changes have been merged, new PDFs are available:
http://ftp.osmocom.org/docs/latest/osmobts-lc15-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-oc2g-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-octphy-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-sysmo-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-trx-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-virtual-vty-reference.pdf