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

[asterisk at phreaknet.org]

On 7/12/2023 8:27 AM, George Joseph wrote:
> On Tue, Jul 11, 2023 at 3:28 PM <asterisk at phreaknet.org 
> <mailto:asterisk at phreaknet.org>> wrote:
>
>     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.

Thanks, I'll play with these further and see if I can solve the include 
omission I had before. Simplification aside, I think this type of stuff 
has been historically underdocumented, so maybe we could have a wiki 
page delving into these? If I come up with any useful notes, I could 
share there as well.

> Only one??   Fixed.

Only one at the time... I just found an extra period in Makefile..inc in 
the latest README, but haven't noticed anything else.

> <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

Got it - this makes a lot more sense now! And yes, you read my mind, I 
don't care about ARI so that did the trick. I noticed the no-mike branch 
no longer exists, but looks like it was merged into main now, so I gave 
that a go and it got much further (sorry, I know it's been a while and I 
wasn't able to test this quickly).

Couldn't have asked for an easier process! It seems like I can just 
clone the repo, copy my Makefile.inc in there, and run make. The above 
was on a relatively fast CPU, but it seems it shouldn't take longer than 
maybe 2 minutes.

The result is a 1.6 GB directory, but it looks like there are 555M for 
latest_api and 511M for Asterisk 20. I guess I really only need "latest" 
(which I'm assuming is master) for the purposes of an application 
reference, since that should be a superset of everything (except stuff 
that's been removed obviously, which I don't care about).

It's also still generating the static docs, not just the dynamic docs, 
which is most of the other space. It looks like from the latest README, 
I can just use Makefile directly instead of Makefile.inc since I only 
need 1 branch, although I kind of like the Makefile.inc now to keep my 
stuff separate from the rest of the repo, and it doesn't look like that 
should make a difference. But if I do "make BRANCH=master" (with 
Makefile.20.inc duplicated to Makefile.master.inc), it doesn't seem to work:

root at debian11:/usr/src/documentation# make BRANCH=master
Creating ./temp/build-master
Setting Up Core Dynamic Documentation for branch 'master'
   Generating markdown from Asterisk XML
ln: failed to create symbolic link 
'./temp/docs/Asterisk_master_Documentation/API_Documentation': No such 
file or directory
make: *** [Makefile:105: dynamic-core-setup] Error 1
root at debian11:/usr/src/documentation# make BRANCH=20
Creating ./temp/build-20
Setting Up Core Dynamic Documentation for branch '20'
   Generating markdown from Asterisk XML
Building to ./temp/site
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: 
/usr/src/documentation/temp/site
INFO     -  Documentation built in 85.57 seconds

 From what I tried initially, I should be able to solve this by deleting 
everything in the docs directory except index.md and the favicon, which 
ensures that there simply is no static content to build. That should 
bring down both the size and the build time. I don't mind doing that at 
all, just wondering is there a good way to not build the static content, 
or would that be the best way?

This is already great by the way, for what I need to it to do - none of 
this is super important though, but if you have any thoughts I'll give 
it another go and see if I can get a more optimized build.