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

[George Joseph]

On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp <jcolp at sangoma.com> wrote:

> On Tue, Jun 20, 2023 at 3:51 PM <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.

Stay tuned!

>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20230620/ac8b777f/attachment.html>