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

[Sylvain Boily]

On 2023-06-21 3:09 p.m., George Joseph wrote:



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


Thanks, i confirm, no cookies on my side now.-- 
_
-- 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

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

[George Joseph]

On Tue, Jun 20, 2023 at 7:20 PM Andrew Latham  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  wrote:
>
>> On 6/20/2023 8:33 PM, George Joseph wrote:
>> > On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp > > > wrote:
>> >
>> > On Tue, Jun 20, 2023 at 3:51 PM > > > 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
>
>
>
> --
> - 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
-- 

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

[Andrew Latham]

Making note on Docs list

On Tue, Jun 20, 2023 at 8:33 AM George Joseph  wrote:

> One of the last tasks in the great Asterisk migration of 2023 is the move
> of the documentation hosted on the Atlassian Confluence wiki to its new
> home at https://docs.asterisk.org.   It's a GitHub Pages backed site
> sourced from a  repo at https://github.com/asterisk/documentation.  We
> did our best to convert all of the existing documentation but some of the
> formatting may still be sub-optimal and a small minority of the links might
> not work but it should be mostly functional.  The one exception is the
> auto-generated documentation for AMI/ARI/Dialplan.  That I'm starting to
> work on now.
>
> Give the new site a look and feel free to start submitting pull requests
> for updates.
>
> --
> George Joseph
> Asterisk Software Developer
> Sangoma Technologies
> Check us out at www.sangoma.com and www.asterisk.org
> --
> _
> -- 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

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

[asterisk]

On 6/20/2023 9:48 PM, Andrew Latham wrote:

https://github.com/asterisk/documentation/pull/2 for the binding topic

On Tue, Jun 20, 2023 at 7:42 PM Andrew Latham > 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`



Thanks, Andrew, for looking into that, and putting those PRs up. Good to 
know that option works. I think he has a point about using a third-party 
server, which is what you'd do anyways, but `mkdocs serve` as a command 
is useless if it can't bind to all interfaces. I don't even use 
containers; to look at the website, it simply has to be bound to all 
interfaces if I want to look at it in a web browser, it's that simple. 
It's very narrow minded to assume that people's workstations are also 
the server that is running XYZ workload, which for me is *never* the case.


The only other thing I can think of at the moment is that it would be 
useful to put the `mkdocs build` command in the README. But this is 
mainly for when the dynamic docs are available, so maybe I'll wait until 
that is finalized as there will probably be more instructions and 
context needed.


--
_
-- 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

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

[Joshua C. Colp]

On Tue, Jun 20, 2023 at 9:53 PM  wrote:



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...)
>

It does work, but the upstream provider was having issues last night so
from a network perspective it was unreachable sporadically. We haven't
touched anything in the old Atlassian stack.

-- 
Joshua C. Colp
Asterisk Project Lead
Sangoma Technologies
Check us out at www.sangoma.com and www.asterisk.org
-- 
_
-- 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

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

[Andrew Latham]

https://github.com/asterisk/documentation/pull/2 for the binding topic

On Tue, Jun 20, 2023 at 7:42 PM Andrew Latham  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  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  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  wrote:
>>>
 On 6/20/2023 8:33 PM, George Joseph wrote:
 > On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp >>> > > wrote:
 >
 > On Tue, Jun 20, 2023 at 3:51 PM >>> > > 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!

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

[Andrew Latham]

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  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  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  wrote:
>>
>>> On 6/20/2023 8:33 PM, George Joseph wrote:
>>> > On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp >> > > wrote:
>>> >
>>> > On Tue, Jun 20, 2023 at 3:51 PM >> > > 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:
>>>

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

[Andrew Latham]

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  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  wrote:
>
>> On 6/20/2023 8:33 PM, George Joseph wrote:
>> > On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp > > > wrote:
>> >
>> > On Tue, Jun 20, 2023 at 3:51 PM > > > 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
>
>
>
> --
> - Andrew "lathama" Latham -
>


-- 
- Andrew "lathama" Latham -
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or 

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

[Andrew Latham]

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  wrote:

> On 6/20/2023 8:33 PM, George Joseph wrote:
> > On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp  > > wrote:
> >
> > On Tue, Jun 20, 2023 at 3:51 PM  > > 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



-- 
- 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

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

[asterisk]

On 6/20/2023 8:33 PM, George Joseph wrote:
On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp > wrote:


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

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

[George Joseph]

On Tue, Jun 20, 2023 at 5:06 PM Joshua C. Colp  wrote:

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

>
>
-- 
_
-- 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

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

[Joshua C. Colp]

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

-- 
Joshua C. Colp
Asterisk Project Lead
Sangoma Technologies
Check us out at www.sangoma.com and www.asterisk.org
-- 
_
-- 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

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

[asterisk]

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?


--
_
-- 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

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

[Joshua C. Colp]

On Tue, Jun 20, 2023 at 11:57 AM Andrew Latham  wrote:

> Ack, so for everyone we should:
>
> * add issues at https://github.com/asterisk/documentation/issues
> * in a bit after the initial gaps are filled we can do patches at
> https://github.com/asterisk/documentation/pulls
> * readme at https://github.com/asterisk/documentation/blob/main/README.md
>

You can immediately do pull requests against the manually written content.

-- 
Joshua C. Colp
Asterisk Project Lead
Sangoma Technologies
Check us out at www.sangoma.com and www.asterisk.org
-- 
_
-- 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

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

[Andrew Latham]

Ack, so for everyone we should:

* add issues at https://github.com/asterisk/documentation/issues
* in a bit after the initial gaps are filled we can do patches at
https://github.com/asterisk/documentation/pulls
* readme at https://github.com/asterisk/documentation/blob/main/README.md

Thanks for your hard work Geroge

On Tue, Jun 20, 2023 at 8:43 AM George Joseph  wrote:

>
>
> On Tue, Jun 20, 2023 at 8:41 AM Andrew Latham  wrote:
>
>> Geroge, it looks and feels good. Grumpy old person would ask why cookies
>> are needed for a documentation site but I have not dug in deep enough yet.
>>
>
> It's just to persist the light/dark theme setting.
>
>
>>
>> On Tue, Jun 20, 2023 at 8:33 AM George Joseph 
>> wrote:
>>
>>> One of the last tasks in the great Asterisk migration of 2023 is the
>>> move of the documentation hosted on the Atlassian Confluence wiki to its
>>> new home at https://docs.asterisk.org.   It's a GitHub Pages backed
>>> site sourced from a  repo at https://github.com/asterisk/documentation.
>>> We did our best to convert all of the existing documentation but some of
>>> the formatting may still be sub-optimal and a small minority of the links
>>> might not work but it should be mostly functional.  The one exception is
>>> the auto-generated documentation for AMI/ARI/Dialplan.  That I'm starting
>>> to work on now.
>>>
>>> Give the new site a look and feel free to start submitting pull requests
>>> for updates.
>>>
>>> --
>>> George Joseph
>>> Asterisk Software Developer
>>> Sangoma Technologies
>>> Check us out at www.sangoma.com and www.asterisk.org
>>> --
>>> _
>>> -- 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
>
> --
> _
> -- 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

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

[George Joseph]

On Tue, Jun 20, 2023 at 8:50 AM Sylvain Boily  wrote:

> Hello,
>
> On 2023-06-20 10:42 a.m., George Joseph wrote:
>
>
>
> On Tue, Jun 20, 2023 at 8:41 AM Andrew Latham  wrote:
>
>> Geroge, it looks and feels good. Grumpy old person would ask why cookies
>> are needed for a documentation site but I have not dug in deep enough yet.
>>
>
> It's just to persist the light/dark theme setting.
>
>
> What i see, it's for google analytics, theme setting is in localstorage.
>

Hmmm.  We don't have any analytics turned on.  I wonder if it has something
to do with the GitHub integration. Let me check.  It's still needed for
localstorage though.




>
> Nice website, thx.
> Sylvain
> --
> _
> -- 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
-- 
_
-- 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

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

[Sylvain Boily]

Hello,

On 2023-06-20 10:42 a.m., George Joseph wrote:



On Tue, Jun 20, 2023 at 8:41 AM Andrew Latham  wrote:

Geroge, it looks and feels good. Grumpy old person would ask why
cookies are needed for a documentation site but I have not dug in
deep enough yet.


It's just to persist the light/dark theme setting.


What i see, it's for google analytics, theme setting is in localstorage.

Nice website, thx.
Sylvain-- 
_
-- 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

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

[George Joseph]

On Tue, Jun 20, 2023 at 8:41 AM Andrew Latham  wrote:

> Geroge, it looks and feels good. Grumpy old person would ask why cookies
> are needed for a documentation site but I have not dug in deep enough yet.
>

It's just to persist the light/dark theme setting.


>
> On Tue, Jun 20, 2023 at 8:33 AM George Joseph  wrote:
>
>> One of the last tasks in the great Asterisk migration of 2023 is the move
>> of the documentation hosted on the Atlassian Confluence wiki to its new
>> home at https://docs.asterisk.org.   It's a GitHub Pages backed site
>> sourced from a  repo at https://github.com/asterisk/documentation.  We
>> did our best to convert all of the existing documentation but some of the
>> formatting may still be sub-optimal and a small minority of the links might
>> not work but it should be mostly functional.  The one exception is the
>> auto-generated documentation for AMI/ARI/Dialplan.  That I'm starting to
>> work on now.
>>
>> Give the new site a look and feel free to start submitting pull requests
>> for updates.
>>
>> --
>> George Joseph
>> Asterisk Software Developer
>> Sangoma Technologies
>> Check us out at www.sangoma.com and www.asterisk.org
>> --
>> _
>> -- 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
-- 
_
-- 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

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

[Andrew Latham]

Geroge, it looks and feels good. Grumpy old person would ask why cookies
are needed for a documentation site but I have not dug in deep enough yet.

On Tue, Jun 20, 2023 at 8:33 AM George Joseph  wrote:

> One of the last tasks in the great Asterisk migration of 2023 is the move
> of the documentation hosted on the Atlassian Confluence wiki to its new
> home at https://docs.asterisk.org.   It's a GitHub Pages backed site
> sourced from a  repo at https://github.com/asterisk/documentation.  We
> did our best to convert all of the existing documentation but some of the
> formatting may still be sub-optimal and a small minority of the links might
> not work but it should be mostly functional.  The one exception is the
> auto-generated documentation for AMI/ARI/Dialplan.  That I'm starting to
> work on now.
>
> Give the new site a look and feel free to start submitting pull requests
> for updates.
>
> --
> George Joseph
> Asterisk Software Developer
> Sangoma Technologies
> Check us out at www.sangoma.com and www.asterisk.org
> --
> _
> -- 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