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 documentation web site

[Joshua C. Colp]

On Wed, Jun 21, 2023 at 10:18 AM Olivier  wrote:

> Hello,
>
> One very useful feature from previous wiki.asterisk.org is giving top
> level/direct access to per version reference doc (see [1 as an
> example]).
> I hope new site will also bring this feature.
>

That is what George is working on now. That is automatically generated
reference documentation from the XML in Asterisk. Only content written by a
person is on the docs site now.

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

[asterisk-dev] New documentation web site

[Olivier]

Hello,

One very useful feature from previous wiki.asterisk.org is giving top
level/direct access to per version reference doc (see [1 as an
example]).
I hope new site will also bring this feature.

[1] https://wiki.asterisk.org/wiki/display/AST/Asterisk+20+Documentation

Cheers

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