Opened 12 years ago

Closed 9 years ago

#3798 closed enhancement (wontfix)

Install user documentation during normal installation

Reported by: Roo <roo.watt@…> Owned by: Robert Kulagowski
Priority: minor Milestone: unknown
Component: Documentation Version: head
Severity: medium Keywords: user documentation install
Cc: Ticket locked: no

Description

Attached is a patch to install the documentation in mythtv/docs during a normal install.

There are two new configure pairs:

  • --enable-user-docbuild, --disable-user-docbuild
  • --enable-dev-docbuild, --disable-dev-docbuild

Install Dir:

  • The install dir is $(PREFIX)/share/doc/mythtv

User Docs:

  • User documentation is under version control and exists in a fresh checkout.
  • User docs will always be installed
  • A make clean will not normally remove the prebuilt user docs
  • If the --enable-user-docbuild is spec'd (and the prereqs are available) the user docs will be built during a "make install" and cleaned during a "make clean"

Dev Docs:

  • The dev docs are built and installed if --enable-dev-docbuild is spec'd
  • Even if --enable-dev-docbuild is not spec'd at configure the dev-docs can be built and installed later with a "make devdocs && make install_devdocs"

There are other make targets to be able to install/uninstall/clean the dev or user docs without the need to reconfigure the entire myth project.

Please let me know if any changes need to be made.

Roo.

PS: This is not in the form of a qmake docs.pro as qmake sucks for this doco type setup, spent some time on the #qt channel but it is buggy when using the custom objects.

Attachments (3)

mythtv_docs_v1.diff (7.6 KB) - added by Roo <roo.watt@…> 12 years ago.
V1 of the documentation installer
mythtv_docs_v2.diff (23.1 KB) - added by Roo <roo.watt@…> 12 years ago.
V2 using qmake, this replaces v1 of the patch
mythtv_docs_v3a.diff (8.7 KB) - added by Roo <roo.watt@…> 12 years ago.
v3a updated for r15810

Download all attachments as: .zip

Change History (21)

Changed 12 years ago by Roo <roo.watt@…>

Attachment: mythtv_docs_v1.diff added

V1 of the documentation installer

comment:1 Changed 12 years ago by Roo <roo.watt@…>

Seems my testing wasn't complete, I just run a make distclean from the mythtv directory and it removed the Makefile from the docs dir. This broke the build system.

Maybe this needs to be done with qmake docs.pro after all. I will look further into it.

PS: This sucks as I thought I tested this, sorry for creating this ticket for a broken patch (at the moment).

Changed 12 years ago by Roo <roo.watt@…>

Attachment: mythtv_docs_v2.diff added

V2 using qmake, this replaces v1 of the patch

comment:2 Changed 12 years ago by Roo <roo.watt@…>

I have reworked the patch, because as mentioned in a previous comment the Makefile version did not play well with qmake.

Most of the commentry in the description is still accurate, except there aren't the number of additional targets.

The configure options --dis/enable-dev-docbuild and --des/enable-user-docbuild are used. If --user-docbuild option is not specified the user docs will just be installed and not rebuilt from the .sgml.

If --dis/enable-dev-docbuild option is used then the dev-docs will be built and install when myth is built and installed. If it is not specified the user can still "make dev-docs" to build the doxygen documentation without the need to reconfigure mythtv.

Due to the limitations of svn diff the following steps are also needed:

  • svn add docs/docs.pro
  • svn propedit svn:ignore docs - add "Makefile", "dummy", "dummy.o", "validate"
  • svn cp themes/dummy.c docs
  • svn rm docs/Makefile
  • svn rm docs/mythtv-HOWTO.html

This patch also uses "tee" for logging the validate output to file as well a displaying it. I believe tee should be part of most distros.

The docs install dir does not contain any version info, this is consistent with the other install dirs and there shouldn't be multiple installed versions of myth anyway (I believe).

Roo.

comment:3 Changed 12 years ago by Roo <roo.watt@…>

With the bugs I have experienced with qmake I should record the version I am using:

cameron@pegasus:~$ qmake --version
Qmake version: 1.07a (Qt 3.3.7)
Qmake is free software from Trolltech AS.

Roo

comment:4 Changed 12 years ago by Roo <roo.watt@…>

If this is accepted, mythtv/keys.txt could get moved to mythtv/docs/default_keys.txt and add

USER_INSTALLS += default_keys.txt

to the docs.pro.

As far as I am aware keys.txt is documentation only, if not another approach may be needed.

comment:5 Changed 12 years ago by stuartm

Component: mythtvdocumentation
Owner: changed from Isaac Richards to Robert Tsai

comment:6 Changed 12 years ago by stuartm

Owner: changed from Robert Tsai to Isaac Richards

comment:7 Changed 12 years ago by danielk

Owner: changed from Isaac Richards to danielk
Status: newassigned

comment:8 Changed 12 years ago by danielk

Milestone: 0.210.22
Status: assignedinfoneeded

patch no longer applies, can you update this to head?

comment:9 Changed 12 years ago by Roo <roo.watt@…>

I have updated the patch, will attach v3a shortly.

If you enable the user doc build you will see the following error:

troff: fatal error: can't find macro file s

The error also occurs when building the user docs from the sgml. Users won't see this normally as there is no need to build the user docs as they are under VC (hence the --enable-users-docs configure option not being listed in the --help output).

Changed 12 years ago by Roo <roo.watt@…>

Attachment: mythtv_docs_v3a.diff added

v3a updated for r15810

comment:10 Changed 12 years ago by Roo <roo.watt@…>

Would a version of this patch be considered for 0.21 that only installed the user documentation?

ie. Didn't have the userdoc build option to configure (which may be not be needed anyway) or the the dev-docs configure option.

Even without the configure options you can still build the user and dev docs from the docs dir with a "make dev-docs" or "make mythtv-HOWTO.pdf" etc.

comment:11 Changed 12 years ago by stuartm

Status: infoneededassigned

comment:12 Changed 11 years ago by danielk

Stuart, I've looked at this and I'm not sure it's a good idea as is. If we want to apply this we should remove the docs/mythtv-HOWTO*.html files and add them and the docs/dummy.c to the svn:ignore list for the docs directory.

comment:13 Changed 11 years ago by danielk

Owner: changed from danielk to stuartm

comment:14 Changed 11 years ago by stuartm

Owner: stuartm deleted
Status: assignednew

comment:15 Changed 11 years ago by Dibblah

Owner: set to Robert Kulagowski
Status: newassigned

comment:16 Changed 10 years ago by stuartm

Component: documentationDocumentation
Milestone: 0.220.23

comment:17 Changed 10 years ago by robertm

Milestone: 0.23unknown

This doesn't seem likely to get done for .23, bumping to unknown until someone picks it up.

comment:18 Changed 9 years ago by robertm

Resolution: wontfix
Status: assignedclosed

Doesn't seem to be any chance that this will happen, nor does the patch show any signs of life.

Note: See TracTickets for help on using tickets.