Re: Generated documentation inside Base

[Andrew Johnson <anj@aps.anl.gov>]

On 01/21/2015 10:35 AM, Ralph Lange wrote:
> As we move the Record Reference Manual from Wiki to being embedded in
> EPICS Base, we need two things:
> 
>  1. An index page for the record documentation.
>     This could use local links for records that have been converted, and
>     links to the Wiki for all other record types.

Agreed.

>  2. A way to push the generated docs onto APS (or other) web space.
>     It would be nice to have an on-line version of these docs (or
>     better: one for each released version of Base and the current
>     development version).

The 3.15 Jenkins build currently publishes some files as artifacts, see
  https://jenkins.aps.anl.gov/view/EPICS%20Base/job/epics-base-3.15/
for links. I do currently limit which files I publish, but I could
change that list to include html/*.

I also manually copy files from each release into the relevant website
directories after each release, so I'm not convinced that we have to
automate that part.

I do have a 'make install' target in the AppDevGuide because that gets
updated more often than we make releases, but again that's currently a
manual process and not at all onerous.

> For 1., I would think a static page should be fine. Things will be
> rarely changing, and I don't know if it is worth adding the complexity
> of an indexing script.

Agreed, an indexing script would be more work than just editing the
index file. We might want to make the index a .pod file, or at least use
the same style.css file to try and unify the look of the documentation.

> For 2., I could imagine an APS Jenkins job that pushes the docs for the
> current version. Released versions would probably still need manual
> intervention/upload.

Do you think we need anything beyond the Jenkins Last Successful Build
links?

- Andrew
-- 
Doctorow's Law: Anytime someone puts a lock on something you own,
    against your wishes, and doesn't give you the key, they're
    not doing it for your benefit.