<div dir="ltr"><div>I'm digesting this. It may be a while. :)</div><div><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sat, Jul 8, 2023 at 4:24 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 6/29/2023 3:14 PM, George Joseph wrote:<br>
> I think we're at a point where the new documentation site can go <br>
> live. The dynamic documentation is integrated and the README file has <br>
> been expanded greatly with information on how the site is built and <br>
> how you can build it yourself.<br>
<br>
Hi, Geroge,<br>
Just had a chance to look at this this afternoon. The 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>
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>
* Since I'm not downloading the docs, I don't think I need the "gh"<br>
tool, and so it doesn't need to be installed for purely generating<br>
documentation. (Also, could be documented as a pre-req, if doing the<br>
download step)<br>
<br>
Then again, when you boil it down to that, it seems like it really comes <br>
down to just:<br>
<br>
* utils/astxml2markdown.py<br>
* mike deploy<br>
<br>
So it seems I'm better off avoiding the makefile and just running the <br>
individual commands needed. I'll end up wrapping it in a script anyways, <br>
but just wondering if there's anything else about the process here I've <br>
missed that wouldn't be conducive to that?<br>
<br>
In particular, it doesn't seem that finagling with Git repositories is <br>
necessary at all to build the dynamic docs. I was able to get it to work <br>
with just this:<br>
<br>
git clone <a href="https://github.com/asterisk/documentation.git" rel="noreferrer" target="_blank">https://github.com/asterisk/documentation.git</a> --depth 1<br>
cd documentation<br>
pip3 install -r requirements.txt<br>
mv docs/favicon.ico docs/index.md .<br>
rm -rf docs/*<br>
mv favicon.ico index.md docs<br>
utils/astxml2markdown.py <br>
--file=/usr/src/asterisk-20.3.0/doc/core-en_US.xml <br>
--xslt=utils/astxml2markdown.xslt --directory=docs/ --branch=20 <br>
--version=20.3.0<br>
mike deploy -F mkdocs.yml 20<br>
rm -rf /var/www/html/asterisk && mv site /var/www/html/asterisk<br>
cd .. && rm -rf documentation<br>
<br>
It seems to work really well. There were just a couple surprises or <br>
annoying aspects:<br>
<br>
* Even with --depth 1, the documentation repo takes a hot minute to<br>
clone, due to all the large PDF artifacts in it, though a tarball of<br>
the repo wouldn't help either if it came with all the static<br>
artifacts anyways. Could probably work around that by cloning it<br>
using svn instead of git, but I was too lazy to do that today.<br>
* For just turning markdown into HTML, mike is pretty slow, it takes<br>
over half a minute just for the dynamic docs (compared to ~1 second<br>
for my previous method, though that was from the original XML to<br>
HTML, not from intermediate markdown)<br>
* Most significantly, the webpages are *huge*. Even just the dynamic<br>
docs are a whopping 228 MB. On average, a documentation page is<br>
almost 250 KB (compared to 1.2 MB the old way for all the<br>
applications, functions, AMI/AGI, and configs on a single webpage -<br>
granted it's not a fair comparison since the menu and what not isn't<br>
repeated that way). Taking a look at the page source of an<br>
application[1], much of the page is whitespace. I know that docs<br>
hosted on GitHub don't need to worry about disk consumption, but for<br>
folks building the docs themselves, I think it might be worth trying<br>
to clean this a little bit. Bloated webpages are obviously also<br>
going to be slower to load as well.<br>
<br>
I haven't yet figured out what's introducing all the extraneous <br>
whitespace. The markdown files seem okay, but things seem to blow up <br>
somewhere in the middle. Ideally we could prevent it from happening in <br>
the first place, but if not, then maybe some fancy recursive <br>
post-processing could strip it all out.<br>
<br>
[1] <a href="https://docs.asterisk.org/20/_Dialplan_Applications/ADSIProg/" rel="noreferrer" target="_blank">https://docs.asterisk.org/20/_Dialplan_Applications/ADSIProg/</a><br>
<br>
</blockquote></div></div>