[asterisk-dev] Final Preview: docs.asterisk.org

[George Joseph]

On Tue, Jul 11, 2023 at 3:28 PM <asterisk at phreaknet.org> wrote:

> On 7/11/2023 4:34 PM, George Joseph wrote:
> > On Sat, Jul 8, 2023 at 4:24 PM <asterisk at phreaknet.org
> > <mailto:asterisk at phreaknet.org>> wrote:
> >
> >     Hi, Geroge,
> >          Just had a chance to look at this this afternoon. The
> >     instructions
> >     for the dynamic doc generation definitely made my head hurt a little
> >     bit, but I have a few thoughts after putzing around a little bit.
> >
> >
> > Your head should be much better now. :)
>
> Much better... the A/C repairman just left too, which helps :)
>

I'll bet.  It was over 102F/39C here in Denver yesterday.


>
> >
> >     My initial thought was that some of the make targets in the Makefile
> >     could be split up a little bit. The version-dynamic target both
> >     downloads documentation source and does the actual build of the
> >     documentation. They could be split into different targets:
> >
> >       * In my case, I don't want to download the upstream Asterisk
> >         documentation, I want to use the local core-en-us.xml, which is a
> >         superset of the documentation available upstream.
> >
> >
> > Uhm are you sure??   The core XML document generated during a build
> > doesn't have the xinclude references de-referenced.  I'd be interested
> > to know what you're seeing.
>
> Mm... yes, you're right about that. I remember encountering that
> limitation when I wrote my converter. I planned to do something about
> it, but never did :)
> My core-en_US.xml and full-en_US.xml files are very similar in size so I
> don't think which one I use would make any difference with this.
>
> As far as "what I'm seeing", this is an example of what I get when I
> take my built XML file at the end of compiling and run it through my
> conversion script: https://asterisk.phreaknet.org/
>
> <snip>

>
> I could keep using this, of course, since nothing has changed with the
> XML and there's no Confluence involved, but what you've done with the
> dynamic docs is way better (and the search capability is really nice),
> so I'd like to migrate to that for internal documentation.
>
> How are the includes *supposed* to be handled, by the way i.e. what's
> supposed to dereference the xincludes? Is it one of the Asterisk build
> scripts for the docs piecing everything together, or is it expected that
> whatever consumes the XML files is able to handle those?
>

XML processing is kinda spread out all over....
* build_tools/get_documentation.py
* build_tools/make_xml_documentation
* loader.c:load_modules().

TBH, I haven't looked at that stuff in years.  It could probably be
simplified quite a bit.


>
> > There are now facilities in the Makefile to get the dynamic sources
> > from your
> > local system.   In that case, gh is not required. Details in the README.
>
> Found a typo in the new README, seems to be just on that branch so I
> guess I can't submit a PR: "CreteDocs"
>

Only one??   Fixed.

<snip>

>
> > You don't need to avoid the Makefile.  You can specify where to get
> > the dynamic sources from and which branches to build.  Details in the
> > README.
>
> I'm a little confused about the BRANCHES variable in Makefile.inc. I
> presume this is irrelevant if using a local XML doc? If only because
> there's only one version of Asterisk compiled (and from which the XML
> doc is sourced). It does specifically say if I'm using local sources I
> need separate Makefile.branch.inc's though so I think I'm not
> understanding something here.
>

> I think I understand why the branches are needed - because now it's
> building all the docs for all the versions into the same site. I think
> my point of confusion is the dynamic doc builder only sees an XML file,
> it can't even possibly know what version of Asterisk that's for without
> being told, can it? I was thinking that make BRANCHES=XX just needs to
> match Makefile.XX.inc, but wasn't sure if there's any other significance
> to these values.
>

You're on the right track.  If you want to do a full build for multiple
branches and wanted to use local documentation for each, you'd need a
Makefile.<branch>.inc  file for each branch whose ASTERISK_XML_FILE
and ASTERISK_ARI_DIR variables point to different sets of source
documentation.  So yes, you'd need a Makefile.<branch>.inc file for each
entry in BRANCHES that you want to use local documentation for.  If you
wanted to, you _could_ use local documentation for only a subset of
branches and retrieve the rest from the Asterisk nightly job.  The trigger
is whether those 2 variables are defined ro a branch or not.

If you only want to build 1 branch, say 20, with local docs, the solution
is even simpler... Just put those 2 variables directly in Makefile.inc and
set BRANCHES := 20.

Makefile.inc:
ASTERISK_XML_FILE := <path>/core-en_US.xml
ASTERISK_ARI_DIR := <path>/rest-api
BRANCHES := 20

Now you can just run 'make' with no options.


>
> It seems to still be trying to download it for me despite adding the
> includes, though I just set up the includes and followed the
> instructions, haven't dug much deeper
>
>
<snip>


>
> root at debian11:/usr/src/documentation# cat Makefile*.inc
> ASTERISK_XML_FILE := /usr/src/asterisk-20.3.0/doc/core-en_US.xml
> BRANCHES := 20
> ASTERISK_XML_FILE := /usr/src/asterisk-20.3.0/doc/core-en_US.xml
>

You're specifying ASTERISK_XML_FILE but not ASTERISK_ARI_DIR so the process
is still going to try to use 'gh' to download the documentation source for
ARI.  I just added the SKIP_ARI variable which can be set in any of the
Makefile.inc files to skip processing of the ARI documentation altogether.
So your Makefile.inc could now look like this:

Makefile.inc:
ASTERISK_XML_FILE := <path>/core-en_US.xml
SKIP_ARI := yes
BRANCHES := 20


>
> >  <snip>
> >
> > File sizes have been significantly reduced by updating mkdocs and
> > using the new navigation.prune option.  I tried removing all of the
> > extra whitespace but after the prune option was applied it made very
> > little difference overall. We can keep looking at it.
> >
>
> Thanks, George, I thought this might be hard to track down but it looks
> like you all solved all the problems in one fell swoop. I need to figure
> out what I did wrong in building but it sounds like this should work
> great. Thank you!
>

Cool!


>
>   NA
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20230712/38141d1f/attachment.html>