[asterisk-dev] New Asterisk Documentation website is available for preview
Andrew Latham
lathama at gmail.com
Tue Jun 20 20:48:00 CDT 2023
https://github.com/asterisk/documentation/pull/2 for the binding topic
On Tue, Jun 20, 2023 at 7:42 PM Andrew Latham <lathama at gmail.com> wrote:
> Read https://github.com/mkdocs/mkdocs/issues/2108 and just have to say
> wow...
>
> This worked for me: `mkdocs serve --dev-addr 0.0.0.00:8000`
>
>
> On Tue, Jun 20, 2023 at 7:34 PM Andrew Latham <lathama at gmail.com> wrote:
>
>> https://github.com/asterisk/documentation/pull/1 for cookies
>>
>> I will look at a 0.0.0.0 binding next
>>
>> 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.
>>>
>>> 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 -
>>>
>>
>>
>> --
>> - Andrew "lathama" Latham -
>>
>
>
> --
> - Andrew "lathama" Latham -
>
--
- Andrew "lathama" Latham -
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20230620/a8b8fef0/attachment.html>
More information about the asterisk-dev
mailing list