<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Jul 11, 2023 at 3:28 PM <<a href="mailto:asterisk@phreaknet.org">asterisk@phreaknet.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 7/11/2023 4:34 PM, George Joseph wrote:<br>
> On Sat, Jul 8, 2023 at 4:24 PM <<a href="mailto:asterisk@phreaknet.org" target="_blank">asterisk@phreaknet.org</a> <br>
> <mailto:<a href="mailto:asterisk@phreaknet.org" target="_blank">asterisk@phreaknet.org</a>>> wrote:<br>
><br>
>     Hi, Geroge,<br>
>          Just had a chance to look at this this afternoon. The<br>
>     instructions<br>
>     for the dynamic doc generation definitely made my head hurt a little<br>
>     bit, but I have a few thoughts after putzing around a little bit.<br>
><br>
><br>
> Your head should be much better now. :)<br>
<br>
Much better... the A/C repairman just left too, which helps :)<br></blockquote><div><br></div><div>I'll bet.  It was over 102F/39C here in Denver yesterday.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
><br>
>     My initial thought was that some of the make targets in the Makefile<br>
>     could be split up a little bit. The version-dynamic target both<br>
>     downloads documentation source and does the actual build of the<br>
>     documentation. They could be split into different targets:<br>
><br>
>       * In my case, I don't want to download the upstream Asterisk<br>
>         documentation, I want to use the local core-en-us.xml, which is a<br>
>         superset of the documentation available upstream.<br>
><br>
><br>
> Uhm are you sure??   The core XML document generated during a build <br>
> doesn't have the xinclude references de-referenced.  I'd be interested <br>
> to know what you're seeing.<br>
<br>
Mm... yes, you're right about that. I remember encountering that <br>
limitation when I wrote my converter. I planned to do something about <br>
it, but never did :)<br>
My core-en_US.xml and full-en_US.xml files are very similar in size so I <br>
don't think which one I use would make any difference with this.<br>
<br>
As far as "what I'm seeing", this is an example of what I get when I <br>
take my built XML file at the end of compiling and run it through my <br>
conversion script: <a href="https://asterisk.phreaknet.org/" rel="noreferrer" target="_blank">https://asterisk.phreaknet.org/</a><br>
<br></blockquote><div><snip> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
I could keep using this, of course, since nothing has changed with the <br>
XML and there's no Confluence involved, but what you've done with the <br>
dynamic docs is way better (and the search capability is really nice), <br>
so I'd like to migrate to that for internal documentation.<br>
<br>
How are the includes *supposed* to be handled, by the way i.e. what's <br>
supposed to dereference the xincludes? Is it one of the Asterisk build <br>
scripts for the docs piecing everything together, or is it expected that <br>
whatever consumes the XML files is able to handle those?<br></blockquote><div><br></div><div><div>XML processing is kinda spread out all over....</div><div>* build_tools/get_documentation.py<br></div><div>* build_tools/make_xml_documentation</div><div><div>* loader.c:load_modules().</div></div><br class="gmail-Apple-interchange-newline"></div><div>TBH, I haven't looked at that stuff in years.  It could probably be simplified quite a bit.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
> There are now facilities in the Makefile to get the dynamic sources <br>
> from your<br>
> local system.   In that case, gh is not required. Details in the README.<br>
<br>
Found a typo in the new README, seems to be just on that branch so I <br>
guess I can't submit a PR: "CreteDocs"<br></blockquote><div><br></div><div>Only one??   Fixed.</div><div> </div><div><snip></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">><br>
> You don't need to avoid the Makefile.  You can specify where to get <br>
> the dynamic sources from and which branches to build.  Details in the <br>
> README.<br>
<br>
I'm a little confused about the BRANCHES variable in Makefile.inc. I <br>
presume this is irrelevant if using a local XML doc? If only because <br>
there's only one version of Asterisk compiled (and from which the XML <br>
doc is sourced). It does specifically say if I'm using local sources I <br>
need separate Makefile.branch.inc's though so I think I'm not <br>
understanding something here.<br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
I think I understand why the branches are needed - because now it's <br>
building all the docs for all the versions into the same site. I think <br>
my point of confusion is the dynamic doc builder only sees an XML file, <br>
it can't even possibly know what version of Asterisk that's for without <br>
being told, can it? I was thinking that make BRANCHES=XX just needs to <br>
match Makefile.XX.inc, but wasn't sure if there's any other significance <br>
to these values.<br></blockquote><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Makefile.inc:</div><div>ASTERISK_XML_FILE := <path>/core-en_US.xml<br>ASTERISK_ARI_DIR := <path>/rest-api<br>BRANCHES := 20<br></div><div><br></div><div>Now you can just run 'make' with no options.</div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
It seems to still be trying to download it for me despite adding the <br>
includes, though I just set up the includes and followed the <br>
instructions, haven't dug much deeper<br>
<br></blockquote><div><br></div><div><snip></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
root@debian11:/usr/src/documentation# cat Makefile*.inc<br>
ASTERISK_XML_FILE := /usr/src/asterisk-20.3.0/doc/core-en_US.xml<br>
BRANCHES := 20<br>
ASTERISK_XML_FILE := /usr/src/asterisk-20.3.0/doc/core-en_US.xml<br></blockquote><div><br></div><div>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:</div><div><br></div><div><div>Makefile.inc:</div><div>ASTERISK_XML_FILE := <path>/core-en_US.xml<br>SKIP_ARI := yes<br>BRANCHES := 20<br></div><div><br></div></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
<br>
>  <snip><br>
><br>
> File sizes have been significantly reduced by updating mkdocs and <br>
> using the new navigation.prune option.  I tried removing all of the <br>
> extra whitespace but after the prune option was applied it made very <br>
> little difference overall. We can keep looking at it.<br>
><br>
<br>
Thanks, George, I thought this might be hard to track down but it looks <br>
like you all solved all the problems in one fell swoop. I need to figure <br>
out what I did wrong in building but it sounds like this should work <br>
great. Thank you!<br></blockquote><div><br></div><div>Cool!</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
  NA<br>
</blockquote></div></div>