Project

General

Profile

Actions

Feature #3385

closed

Move project specific manuals from osmo-gsm-manuals to each respective git repository

Added by pespin over 5 years ago. Updated over 5 years ago.

Status:
Resolved
Priority:
Normal
Assignee:
Target version:
-
Start date:
07/06/2018
Due date:
% Done:

100%

Spec Reference:

Description

Following subdirs in osmo-gsm-manuals.git should be moved under doc subdir of each respective git repository (osmo-bsc.git, osmo-bts.git, etc.)

OsmoBSC
OsmoBTS
OsmocomBB
OsmoGGSN
OsmoGSMTester
OsmoHLR
OsmoMGCP
OsmoMGW
OsmoMSC
OsmoNAT
OsmoNITB
OsmoPCU
OsmoSGSN
OsmoSTP
OsmoTRX

The idea is to keep the common parts and build related scripts (makefile, etc) in osmo-gsm-manuals.git, and then conditionally enable building them by using a configure flag (eg. --enable-man --with-man-path=/path/to/osmo-gsm-manuals.git/).

We can have most of the Makefile logic in a .mk file in osmo-gsm-manuals.git and include it in every repository, similar to what we do with osmo-release.mk from libosmocore.git:
In configure.ac:

dnl include release helper
RELMAKE='-include osmo-release.mk'
AC_SUBST([RELMAKE])

This way we can have user manual and VTY documentation up to date and sync with code, and force to have documentation changes together with code changes in the same gerrit patch before +2 it.

This will also allow to easily generate man pages from a specific .adoc file (which is also included in user manual).


Files

move-manuals.tar.gz move-manuals.tar.gz 1.26 KB osmith, 11/23/2018 03:23 PM

Checklist

  • add manuals with commit history to the project repos (run the attached script)
  • repos using autotools: integrate with configure.ac, toplevel Makefile.am etc.
  • repos not using autotools: rename Makefile.am to Makefile and adjust it slightly
  • configure jenkins to build all manuals in the gerrit build verification
  • configure jenkins to build and publish manuals when a commit is merged to master
  • delete project manuals from osmo-gsm-manuals.git
  • Osmocom Docker image: add dependencies for osmo-gsm-manuals
  • integrate manuals to osmocom-bb.git, openbsc.git, osmo-gsm-tester.git
  • contrib/jenkins.sh: build manuals and add --publish option
  • remove remaining project related files from osmo-gsm-manuals.git
  • jenkins job: master-builds.yml: run all project's contrib/jenkins.sh with --publish
  • build and publish manuals for repos without configure.ac in the root directory (osmocom-bb, openbsc, osmo-gsm-tester)
  • whitelist the jenkins bots SSH keys for uploading to the docs server
  • enable PUBLISH=1 again (temporarily disabled due to missing upload permissions)

Related issues

Related to OsmoBSC - Feature #3583: OsmoBSC manual: copy/move bts-examples chapter from OsmoNITBResolvedosmith09/20/2018

Actions
Related to Cellular Network Infrastructure - Bug #3725: Jenkins isn't using the credentials store for uploading to rita.osmocom.orgResolvedosmith12/12/2018

Actions
Related to Cellular Network Infrastructure - Bug #3726: Jenkins: build all Osmocom projects in docker, not only someResolvedosmith12/12/2018

Actions
Blocked by Cellular Network Infrastructure - Bug #3720: Jenkins can't upload to rita.osmocom.orgResolvedosmith12/06/2018

Actions
Precedes Cellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc filesNewosmith07/09/2018

Actions
Precedes Cellular Network Infrastructure - Feature #3695: generate VTY reference manuals from 'make' directlyRejectedosmith

Actions
Actions

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)