[asterisk-dev] New Asterisk Documentation website is available for preview

[asterisk at phreaknet.org]

On 6/20/2023 8:33 PM, George Joseph wrote:
> On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp <jcolp at sangoma.com 
> <mailto:jcolp at sangoma.com>> wrote:
>
>     On Tue, Jun 20, 2023 at 3:51 PM <asterisk at phreaknet.org
>     <mailto:asterisk at phreaknet.org>> wrote:
>
>         On 6/20/2023 10:32 AM, George Joseph wrote:
>         > The one exception is the auto-generated documentation for
>         > AMI/ARI/Dialplan.  That I'm starting to work on now.
>         Thanks, George - I see from the README that one can run this
>         on a local
>         webserver. Will the auto-generated documentation aspect tie in
>         with this
>         as well? I wrote my own xmldoc to HTML generator a while back
>         so I can
>         view documentation for out of tree modules. If this can do
>         that out of
>         the box, then that would certainly be nice functionality to take
>         advantage of. Will it just be sourcing from a core xml file,
>         that we can
>         point elsewhere if we want, or is that going to remain more
>         upstream
>         specific like it was with Confluence?
>
>
>     I don't know how George plans to approach it fully, but ultimately
>     the reference documentation will also end up as markdown and
>     consumed with mkdocs. I do not expect those markdown files to be
>     checked into the tree but generated as part of the deploy process.
>     Any tooling to consume the XML and produce the markdown files will
>     be available, so if someone wanted it locally they could.
>
>
> Each version of Asterisk generates between 800 and 900 pages of 
> dynamic docs so it's going to take a bit of thought on how to 
> integrate them.  As Josh noted, we don't want those markdown files 
> checked into the repo but we do want mkdocs to integrate them 
> seamlessly into the main docs site, including the search indexing.  
>  We could run a full site build once a night to convert the static and 
> dynamic pages into html and index them all BUT we don't have 
> server-side searching available so it's done in the browser and right 
> now, even without the dynamic pages, the search_index.json file is 
> 4.1MB.  This might make it prudent to create a "virtual" site with its 
> own index just for the dynamic docs and link to it from the main 
> site.   Maybe even a separate virtual site for each Asterisk version.  
>  In fact, there are tools to create a versioned API site already 
> available. Kind of like how Python does it with a drop down at the top 
> of every page to select the Python version you want to see the 
> documentation for.

Thanks, George - that helps!
I was a bit surprised by how fast the search results were on the new 
site. It seems to be a lot better than the old wiki (which doesn't seem 
to work anymore, either...)

There does seem to be an issue with the web hosting. It seems to be running:
root at debian11:/usr/src/documentation# mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 16.96 seconds
INFO     -  [20:42:02] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [20:42:02] Serving on http://127.0.0.1:8000/

But if I navigate to port 8000 on that machine in my browser, I get 
nothing... nothing even seems to be listening on that port.
It works if I curl localhost on that server, so it seems to be listening 
on just the loopback address. I don't really see how that's helpful - it 
should probably be listening on all interfaces, so one can see what it 
looks like graphically, no?

Realistically though, I wouldn't want to run a separate python server 
anyways, I just want static webpages I can serve in an Apache 
virtualhost, like my current doc generation process. It seems if I run 
"mkbuild docs" it does that. So if the dynamic docs have a similar 
process this seems like it will work great!