On 6/20/2023 8:33 PM, George Joseph wrote:
On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp <jc...@sangoma.com
<mailto:jc...@sangoma.com>> wrote:
On Tue, Jun 20, 2023 at 3:51 PM <aster...@phreaknet.org
<mailto:aster...@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@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!
--
_____________________________________________________________________
-- 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
