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

[George Joseph]

On Tue, Jun 20, 2023 at 7:20 PM Andrew Latham <lathama at gmail.com> wrote:

> Maybe file an issue at https://github.com/asterisk/documentation/issues
>
> I just tested and it works on localhost for me. It also prompted me for
> cookies so I will do a PR for that.
>

PR to disable cookies has been merged.


>
> On Tue, Jun 20, 2023 at 6:53 PM <asterisk at phreaknet.org> wrote:
>
>> 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!
>>
>> --
>> _____________________________________________________________________
>> -- 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
>
>
>
> --
> - Andrew "lathama" Latham -
> --
> _____________________________________________________________________
> -- 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20230621/bb727c19/attachment.html>