On 7/12/2023 8:27 AM, George Joseph wrote:
On Tue, Jul 11, 2023 at 3:28 PM <aster...@phreaknet.org
<mailto:aster...@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@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@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@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.
--
_____________________________________________________________________
-- Bandwidth and Colocation Provided by http://www.api-digital.com --
asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/asterisk-dev
