Re: [asterisk-dev] Final Preview: docs.asterisk.org

[Floimair Florian]

Hi George!

Something I noticed (e.g. on this page: 
https://docs.asterisk.org/Asterisk_20_Documentation/API_Documentation/Module_Configuration/res_pjsip/)

The available space in the browser is used badly with the current layout 
template.
There is a lot of blank space to the left and right, while the important 
content of the tables in the middle is in fact cropped and the browser even 
shows a horizontal scrollbar for the middle part.

I am using a 16:9 display so I guess I am not that exotic in the way the 
content is presented to me.

Can we somehow make better use of the space? E.g. make the left and right 
sections (left: “Asterisk Documentation”, right: “Table of contents”) static to 
the left and right and use whatever space is available for the main content in 
the middle.



FLORIAN FLOIMAIR
Development
Symphony Cloud Services
Commend International GmbH
Saalachstrasse 51
5020 Salzburg, Austria
Phone: +43 662 85 62 25
Mail: f.floim...@commend.com
[signature_2176956728]
commend.com
LG Salzburg / FN 178618z

-- 
_
-- 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] Final Preview: docs.asterisk.org

[asterisk]

On 8/4/2023 3:20 PM, George Joseph wrote:
On Fri, Aug 4, 2023 at 11:50 AM > wrote:


Only thing I noticed when building this time around was warnings
like these:
INFO    -  Doc file

'Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/SMDI_MSG_RETRIEVE.md'

contains an absolute link
'/Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/SMDI_MSG',

it was left as is. Did you mean 'SMDI_MSG.md'?
INFO    -  Doc file

'Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/STREAM_SILENCE.md'

contains an absolute link

'/Asterisk_20_Documentation/API_Documentation/Dialplan_Applications/ChanSpy',

it was left as is. Did you mean
    '../Dialplan_Applications/ChanSpy.md'?


Since I don't get those errors I assume they're your own added 
documentation?  I can't really help there.  All I can say is to look 
at how the standard documentation references other pages.  To make 
sure the links work in different versions of asterisk, they need to be 
relative, like the last error message above.


No, I was seeing this for everything (e.g. ChanSpy and SMDI_MSG_RETRIEVE 
above). But if you're not getting them, then maybe I (probably) missed 
something. Since everything worked regardless, I don't think we need to 
worry about this then. If I notice an actual issue down the line, I'll 
look into that and flag if needed, but right now all's good.


--
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

On Fri, Aug 4, 2023 at 11:50 AM  wrote:

> On 8/4/2023 9:42 AM, George Joseph wrote:
> > Well, I've made a few more changes and pushed them up.  I think this
> > is as good as it's going to get for now.
>
> I think it's perfect. Down from 230 MB to 140 MB for the same build. 40%
> size reduction just by removing whitespace I guess! Looking at a few
> pages manually, the HTML looks perfect. No visible issues.
>
> Only thing I noticed when building this time around was warnings like
> these:
> INFO-  Doc file
> 'Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/SMDI_MSG_RETRIEVE.md'
>
> contains an absolute link
> '/Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/SMDI_MSG',
>
> it was left as is. Did you mean 'SMDI_MSG.md'?
> INFO-  Doc file
> 'Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/STREAM_SILENCE.md'
>
> contains an absolute link
> '/Asterisk_20_Documentation/API_Documentation/Dialplan_Applications/ChanSpy',
>
> it was left as is. Did you mean
> '../Dialplan_Applications/ChanSpy.md'?
>
>
Since I don't get those errors I assume they're your own added
documentation?  I can't really help there.  All I can say is to look at how
the standard documentation references other pages.  To make sure the links
work in different versions of asterisk, they need to be relative, like the
last error message above.


> However I tested the site and things seem to work fine. The build did
> take longer, possibly due to the above checks, 90 seconds vs 18, but
> that's not really an issue. The links do appear to be relative to me -
> I'm not putting this in a domain root, but in a subfolder, and the links
> all seem to work correctly for me. So I don't think there's an issue and
> it seems like this can be ignored - perhaps it went ahead and converted
> it on the fly. Just wanted to point that out in case I'm wrong.
>
> Everything seems to work well, I don't see any further issues with
> anything here. Thanks a lot George for looking into these issues, I'm
> looking forward to porting documentation over to this new generation
> method.
>
-- 
_
-- 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] Final Preview: docs.asterisk.org

[asterisk]

On 8/4/2023 9:42 AM, George Joseph wrote:
Well, I've made a few more changes and pushed them up.  I think this 
is as good as it's going to get for now.


I think it's perfect. Down from 230 MB to 140 MB for the same build. 40% 
size reduction just by removing whitespace I guess! Looking at a few 
pages manually, the HTML looks perfect. No visible issues.


Only thing I noticed when building this time around was warnings like these:
INFO    -  Doc file 
'Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/SMDI_MSG_RETRIEVE.md' 
contains an absolute link
'/Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/SMDI_MSG', 
it was left as is. Did you mean 'SMDI_MSG.md'?
INFO    -  Doc file 
'Asterisk_20_Documentation/API_Documentation/Dialplan_Functions/STREAM_SILENCE.md' 
contains an absolute link
'/Asterisk_20_Documentation/API_Documentation/Dialplan_Applications/ChanSpy', 
it was left as is. Did you mean

   '../Dialplan_Applications/ChanSpy.md'?

However I tested the site and things seem to work fine. The build did 
take longer, possibly due to the above checks, 90 seconds vs 18, but 
that's not really an issue. The links do appear to be relative to me - 
I'm not putting this in a domain root, but in a subfolder, and the links 
all seem to work correctly for me. So I don't think there's an issue and 
it seems like this can be ignored - perhaps it went ahead and converted 
it on the fly. Just wanted to point that out in case I'm wrong.


Everything seems to work well, I don't see any further issues with 
anything here. Thanks a lot George for looking into these issues, I'm 
looking forward to porting documentation over to this new generation method.


--
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

Well, I've made a few more changes and pushed them up.  I think this is as
good as it's going to get for now.

On Fri, Jul 28, 2023 at 6:56 PM  wrote:

> On 7/28/2023 8:48 PM, George Joseph wrote:
> > On Fri, Jul 28, 2023 at 1:52 PM  > > wrote:
> >
> >
> > It's at the very bottom of the README:
> > > If you're always going to build just 1 branch's dynamic
> > documentation,
> > > you can skip the Makefile..inc file and just place everything in
> > the
> > > main Makefile.inc:
> >
> > The first Makefile..inc has an extra period world's least
> > important
> > typo.
> >
> >
> > Ahha!   It's 'Makefile..inc' in the source README.md but the
> > '' is getting stripped. :)
>
> Ah, probably should've noticed that, actually, Makefile.inc twice in a
> row doesn't make any sense, if I was actually thinking about it...
>
> > Circling back to one other thing now that this seems good to go, what
> > exactly did you change for reducing the file sizes / is that
> > included in
> > the current iteration, without mike?
> >
> >
> > The addition of "navigation.prune" under features in mkdocs.yml did
> > most of it, and yes, it's currently included.
> >
> > I'm still seeing a lot of
> > extraneous whitespace in the pages. 244 KB per page isn't huge,
> > but just
> > at a cursory glance,
> >
> >
> > Can you give me an example of an html page that's that big?  Most I
> > see are in the 80-100k range
>
> I think all of them - for example:
>
> https://docs.asterisk.org/Asterisk_20_Documentation/API_Documentation/Dialplan_Applications/ADSIProg/
>
> This one is "only" 131 KB, but if you go and view source, you can scroll
> down a bit and see often hundreds of newlines, tabs, and spaces at a
> time in a row. I can't work how that's creeping in from the markdown, so
> I don't think it's from the markdown. That's why I thought we might need
> to do it manually, e.g. using tr or something like that. So regardless
> of page size, I think we could likely prune all the pages down just by
> eliminating whitespace.
>
> >
> > I think we could probably cut the size 10-20% just
> > by getting rid of the whitespace. In some places, there are just
> > hundreds of newlines in a row for no reason.
> >
> >
> > Give me an example page.
> >
> > If this is just what the
> > tool generates, I understand that, we don't have any control over
> > that,
> > just wanted to know. We could remove it all pretty easily with sed
> > probably, and think could be a final "post processing" step in the
> > Makefile, run recursively on all files. What do you think?
> >
> >
> > I tried to do exactly that but it didn't result in much savings and I
> > got nervous about accidentally deleting multiple "blank" lines without
> > knowing whether you might be in a "" block or not.   I was going
> > to try html-minifier but just haven't got to it yet.
>
> Yeah, I guess that could be tricky. But how much is the  tag
> actually used? On the page linked above, for example, I only see it
> once, and, ironically, there isn't any extraneous whitespace in it.  I
> took a look at a few different types of pages and this appears to be the
> case for all of them. So in our particular case, it seems like it might
> be okay to do a simple delete, since  shouldn't be affected by
> consecutive whitespace.
>
-- 
_
-- 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] Final Preview: docs.asterisk.org

[asterisk]

On 7/28/2023 8:48 PM, George Joseph wrote:
On Fri, Jul 28, 2023 at 1:52 PM > wrote:



It's at the very bottom of the README:
> If you're always going to build just 1 branch's dynamic
documentation,
> you can skip the Makefile..inc file and just place everything in
the
> main Makefile.inc:

The first Makefile..inc has an extra period world's least
important
typo.


Ahha!   It's 'Makefile..inc' in the source README.md but the 
'' is getting stripped. :)


Ah, probably should've noticed that, actually, Makefile.inc twice in a 
row doesn't make any sense, if I was actually thinking about it...



Circling back to one other thing now that this seems good to go, what
exactly did you change for reducing the file sizes / is that
included in
the current iteration, without mike?


The addition of "navigation.prune" under features in mkdocs.yml did 
most of it, and yes, it's currently included.


I'm still seeing a lot of
extraneous whitespace in the pages. 244 KB per page isn't huge,
but just
at a cursory glance, 



Can you give me an example of an html page that's that big?  Most I 
see are in the 80-100k range


I think all of them - for example: 
https://docs.asterisk.org/Asterisk_20_Documentation/API_Documentation/Dialplan_Applications/ADSIProg/


This one is "only" 131 KB, but if you go and view source, you can scroll 
down a bit and see often hundreds of newlines, tabs, and spaces at a 
time in a row. I can't work how that's creeping in from the markdown, so 
I don't think it's from the markdown. That's why I thought we might need 
to do it manually, e.g. using tr or something like that. So regardless 
of page size, I think we could likely prune all the pages down just by 
eliminating whitespace.




I think we could probably cut the size 10-20% just
by getting rid of the whitespace. In some places, there are just
hundreds of newlines in a row for no reason.


Give me an example page.

If this is just what the
tool generates, I understand that, we don't have any control over
that,
just wanted to know. We could remove it all pretty easily with sed
probably, and think could be a final "post processing" step in the
Makefile, run recursively on all files. What do you think?


I tried to do exactly that but it didn't result in much savings and I 
got nervous about accidentally deleting multiple "blank" lines without 
knowing whether you might be in a "" block or not.   I was going 
to try html-minifier but just haven't got to it yet.


Yeah, I guess that could be tricky. But how much is the  tag 
actually used? On the page linked above, for example, I only see it 
once, and, ironically, there isn't any extraneous whitespace in it.  I 
took a look at a few different types of pages and this appears to be the 
case for all of them. So in our particular case, it seems like it might 
be okay to do a simple delete, since  shouldn't be affected by 
consecutive whitespace.


--
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

On Fri, Jul 28, 2023 at 6:48 PM George Joseph  wrote:

>
>
> On Fri, Jul 28, 2023 at 1:52 PM  wrote:
>
>>
>> It's at the very bottom of the README:
>> > If you're always going to build just 1 branch's dynamic documentation,
>> > you can skip the Makefile..inc file and just place everything in the
>> > main Makefile.inc:
>>
>> The first Makefile..inc has an extra period world's least important
>> typo.
>>
>
> Ahha!   It's 'Makefile..inc' in the source README.md but the
> '' is getting stripped. :)
>
>
>
>> Circling back to one other thing now that this seems good to go, what
>> exactly did you change for reducing the file sizes / is that included in
>> the current iteration, without mike?
>
>
> The addition of "navigation.prune" under features in mkdocs.yml did most
> of it, and yes, it's currently included.
>
>
>> I'm still seeing a lot of
>> extraneous whitespace in the pages. 244 KB per page isn't huge, but just
>> at a cursory glance,
>
>
> Can you give me an example of an html page that's that big?  Most I see
> are in the 80-100k range
>
>
>> I think we could probably cut the size 10-20% just
>> by getting rid of the whitespace. In some places, there are just
>> hundreds of newlines in a row for no reason.
>
>
> Give me an example page.
>
>
>> If this is just what the
>> tool generates, I understand that, we don't have any control over that,
>> just wanted to know. We could remove it all pretty easily with sed
>> probably, and think could be a final "post processing" step in the
>> Makefile, run recursively on all files. What do you think?
>>
>
> I tried to do exactly that but it didn't result in much savings and I got
> nervous about accidentally deleting multiple "blank" lines without knowing
> whether you might be in a "" block or not.   I was going to
> try html-minifier but just haven't got to it yet.
>

Oh, there's a mkdocs plugin called "minify".  I can give that a try.



>
>
>
-- 
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

On Fri, Jul 28, 2023 at 1:52 PM  wrote:

>
> It's at the very bottom of the README:
> > If you're always going to build just 1 branch's dynamic documentation,
> > you can skip the Makefile..inc file and just place everything in the
> > main Makefile.inc:
>
> The first Makefile..inc has an extra period world's least important
> typo.
>

Ahha!   It's 'Makefile..inc' in the source README.md but the
'' is getting stripped. :)



> Circling back to one other thing now that this seems good to go, what
> exactly did you change for reducing the file sizes / is that included in
> the current iteration, without mike?


The addition of "navigation.prune" under features in mkdocs.yml did most of
it, and yes, it's currently included.


> I'm still seeing a lot of
> extraneous whitespace in the pages. 244 KB per page isn't huge, but just
> at a cursory glance,


Can you give me an example of an html page that's that big?  Most I see are
in the 80-100k range


> I think we could probably cut the size 10-20% just
> by getting rid of the whitespace. In some places, there are just
> hundreds of newlines in a row for no reason.


Give me an example page.


> If this is just what the
> tool generates, I understand that, we don't have any control over that,
> just wanted to know. We could remove it all pretty easily with sed
> probably, and think could be a final "post processing" step in the
> Makefile, run recursively on all files. What do you think?
>

I tried to do exactly that but it didn't result in much savings and I got
nervous about accidentally deleting multiple "blank" lines without knowing
whether you might be in a "" block or not.   I was going to
try html-minifier but just haven't got to it yet.
-- 
_
-- 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] Final Preview: docs.asterisk.org

[asterisk]

On 7/24/2023 8:27 AM, George Joseph wrote:



Only one at the time... I just found an extra period in
Makefile..inc in
the latest README, but haven't noticed anything else.

Not seeing it.  Probably fixed already.


It's at the very bottom of the README:
If you're always going to build just 1 branch's dynamic documentation, 
you can skip the Makefile..inc file and just place everything in the 
main Makefile.inc:


The first Makefile..inc has an extra period world's least important 
typo.



> Makefile.inc:
> ASTERISK_XML_FILE := /core-en_US.xml
> SKIP_ARI := yes
> BRANCHES := 20

Got it - this makes a lot more sense now! And yes, you read my
mind, I
don't care about ARI so that did the trick. I noticed the no-mike
branch
no longer exists, but looks like it was merged into main now, so I
gave
that a go and it got much further (sorry, I know it's been a while
and I
wasn't able to test this quickly).

Couldn't have asked for an easier process! It seems like I can just
clone the repo, copy my Makefile.inc in there, and run make. The
above
was on a relatively fast CPU, but it seems it shouldn't take
longer than
maybe 2 minutes.

The result is a 1.6 GB directory, 



Eh what?  When I build everything, temp/site is only 574M.  Maybe need 
to clean everything out or is your own stuff just that big?


No, I probably screwed it up somehow; "make clean" didn't remove any of 
the generated files, but it didn't give me a target error so I just 
assumed that would do what it needed to do. This time I explicitly did 
an rm -rf temp/site beforehand to ensure it would be clean.




 From what I tried initially, I should be able to solve this by
deleting
everything in the docs directory except index.md and the favicon,
which
ensures that there simply is no static content to build. That should
bring down both the size and the build time. I don't mind doing
that at
all, just wondering is there a good way to not build the static
content,
or would that be the best way?


Do a git pull :)
You should now be able to do...
"make BRANCH=master NO_STATIC=yes"

You can add NO_STATIC=yes to your makefile.inc instead.

Thanks George! This looks much more promising:

root@debian11:/usr/src/documentation# rm -rf temp/site/
root@debian11:/usr/src/documentation# make BRANCH=20
Creating ./temp/build-20
Setting Up Core Dynamic Documentation for branch '20'
  Generating markdown from Asterisk XML
Building to ./temp/site
INFO -  Cleaning site directory
INFO -  Building documentation to directory: 
/usr/src/documentation/temp/site

INFO -  Documentation built in 15.67 seconds

Now it's only 230 MB in total. The site builds quickly and it's exactly 
what I was looking for when I opened it up - perfect!


Circling back to one other thing now that this seems good to go, what 
exactly did you change for reducing the file sizes / is that included in 
the current iteration, without mike? I'm still seeing a lot of 
extraneous whitespace in the pages. 244 KB per page isn't huge, but just 
at a cursory glance, I think we could probably cut the size 10-20% just 
by getting rid of the whitespace. In some places, there are just 
hundreds of newlines in a row for no reason. If this is just what the 
tool generates, I understand that, we don't have any control over that, 
just wanted to know. We could remove it all pretty easily with sed 
probably, and think could be a final "post processing" step in the 
Makefile, run recursively on all files. What do you think?


--
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

>
>
> >
> > TBH, I haven't looked at that stuff in years.  It could probably be
> > simplified quite a bit.
>
> Thanks, I'll play with these further and see if I can solve the include
> omission I had before. Simplification aside, I think this type of stuff
> has been historically underdocumented, so maybe we could have a wiki
> page delving into these? If I come up with any useful notes, I could
> share there as well.
>

Good idea.


>
> > Only one??   Fixed.
>
> Only one at the time... I just found an extra period in Makefile..inc in
> the latest README, but haven't noticed anything else.
>
> Not seeing it.  Probably fixed already.


> > Makefile.inc:
> > ASTERISK_XML_FILE := /core-en_US.xml
> > SKIP_ARI := yes
> > BRANCHES := 20
>
> Got it - this makes a lot more sense now! And yes, you read my mind, I
> don't care about ARI so that did the trick. I noticed the no-mike branch
> no longer exists, but looks like it was merged into main now, so I gave
> that a go and it got much further (sorry, I know it's been a while and I
> wasn't able to test this quickly).
>
> Couldn't have asked for an easier process! It seems like I can just
> clone the repo, copy my Makefile.inc in there, and run make. The above
> was on a relatively fast CPU, but it seems it shouldn't take longer than
> maybe 2 minutes.
>
> The result is a 1.6 GB directory,


Eh what?  When I build everything, temp/site is only 574M.  Maybe need to
clean everything out or is your own stuff just that big?


> but it looks like there are 555M for
> latest_api and 511M for Asterisk 20. I guess I really only need "latest"
> (which I'm assuming is master) for the purposes of an application
> reference, since that should be a superset of everything (except stuff
> that's been removed obviously, which I don't care about).
>

In docs, latest_api is a symlink to 20 but when mkdocs creates the site, it
doesn't preserve that symlink.   Will eventually fix that.


>
> It's also still generating the static docs, not just the dynamic docs,
> which is most of the other space.


See below.


> It looks like from the latest README,
> I can just use Makefile directly instead of Makefile.inc since I only
> need 1 branch, although I kind of like the Makefile.inc now to keep my
> stuff separate from the rest of the repo, and it doesn't look like that
> should make a difference. But if I do "make BRANCH=master" (with
> Makefile.20.inc duplicated to Makefile.master.inc), it doesn't seem to
> work:
>
> root@debian11:/usr/src/documentation# make BRANCH=master
> Creating ./temp/build-master
> Setting Up Core Dynamic Documentation for branch 'master'
>Generating markdown from Asterisk XML
> ln: failed to create symbolic link
> './temp/docs/Asterisk_master_Documentation/API_Documentation': No such
> file or directory
> make: *** [Makefile:105: dynamic-core-setup] Error 1
>

One of the reasons for needing the static docs is that's what creates the
directory structure including the subdirectories for each branch's API
documentation.  Since we don't build documentation for master there's no
directory for it.

See below...


>
>  From what I tried initially, I should be able to solve this by deleting
> everything in the docs directory except index.md and the favicon, which
> ensures that there simply is no static content to build. That should
> bring down both the size and the build time. I don't mind doing that at
> all, just wondering is there a good way to not build the static content,
> or would that be the best way?
>

Do a git pull :)
You should now be able to do...
"make BRANCH=master NO_STATIC=yes"

You can add NO_STATIC=yes to your makefile.inc instead.


> This is already great by the way, for what I need to it to do - none of
> this is super important though, but if you have any thoughts I'll give
> it another go and see if I can get a more optimized build.
>
-- 
_
-- 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] Final Preview: docs.asterisk.org

[asterisk]

On 7/12/2023 8:27 AM, George Joseph wrote:
On Tue, Jul 11, 2023 at 3:28 PM > wrote:


How are the includes *supposed* to be handled, by the way i.e. what's
supposed to dereference the xincludes? Is it one of the Asterisk
build
scripts for the docs piecing everything together, or is it
expected that
whatever consumes the XML files is able to handle those?


XML processing is kinda spread out all over
* build_tools/get_documentation.py
* build_tools/make_xml_documentation
* loader.c:load_modules().

TBH, I haven't looked at that stuff in years.  It could probably be 
simplified quite a bit.


Thanks, I'll play with these further and see if I can solve the include 
omission I had before. Simplification aside, I think this type of stuff 
has been historically underdocumented, so maybe we could have a wiki 
page delving into these? If I come up with any useful notes, I could 
share there as well.



Only one??   Fixed.


Only one at the time... I just found an extra period in Makefile..inc in 
the latest README, but haven't noticed anything else.






root@debian11:/usr/src/documentation# cat Makefile*.inc
ASTERISK_XML_FILE := /usr/src/asterisk-20.3.0/doc/core-en_US.xml
BRANCHES := 20
ASTERISK_XML_FILE := /usr/src/asterisk-20.3.0/doc/core-en_US.xml


You're specifying ASTERISK_XML_FILE but not ASTERISK_ARI_DIR so the 
process is still going to try to use 'gh' to download the 
documentation source for ARI.  I just added the SKIP_ARI variable 
which can be set in any of the Makefile.inc files to skip processing 
of the ARI documentation altogether.  So your Makefile.inc could now 
look like this:


Makefile.inc:
ASTERISK_XML_FILE := /core-en_US.xml
SKIP_ARI := yes
BRANCHES := 20


Got it - this makes a lot more sense now! And yes, you read my mind, I 
don't care about ARI so that did the trick. I noticed the no-mike branch 
no longer exists, but looks like it was merged into main now, so I gave 
that a go and it got much further (sorry, I know it's been a while and I 
wasn't able to test this quickly).


Couldn't have asked for an easier process! It seems like I can just 
clone the repo, copy my Makefile.inc in there, and run make. The above 
was on a relatively fast CPU, but it seems it shouldn't take longer than 
maybe 2 minutes.


The result is a 1.6 GB directory, but it looks like there are 555M for 
latest_api and 511M for Asterisk 20. I guess I really only need "latest" 
(which I'm assuming is master) for the purposes of an application 
reference, since that should be a superset of everything (except stuff 
that's been removed obviously, which I don't care about).


It's also still generating the static docs, not just the dynamic docs, 
which is most of the other space. It looks like from the latest README, 
I can just use Makefile directly instead of Makefile.inc since I only 
need 1 branch, although I kind of like the Makefile.inc now to keep my 
stuff separate from the rest of the repo, and it doesn't look like that 
should make a difference. But if I do "make BRANCH=master" (with 
Makefile.20.inc duplicated to Makefile.master.inc), it doesn't seem to work:


root@debian11:/usr/src/documentation# make BRANCH=master
Creating ./temp/build-master
Setting Up Core Dynamic Documentation for branch 'master'
  Generating markdown from Asterisk XML
ln: failed to create symbolic link 
'./temp/docs/Asterisk_master_Documentation/API_Documentation': No such 
file or directory

make: *** [Makefile:105: dynamic-core-setup] Error 1
root@debian11:/usr/src/documentation# make BRANCH=20
Creating ./temp/build-20
Setting Up Core Dynamic Documentation for branch '20'
  Generating markdown from Asterisk XML
Building to ./temp/site
INFO -  Cleaning site directory
INFO -  Building documentation to directory: 
/usr/src/documentation/temp/site

INFO -  Documentation built in 85.57 seconds

From what I tried initially, I should be able to solve this by deleting 
everything in the docs directory except index.md and the favicon, which 
ensures that there simply is no static content to build. That should 
bring down both the size and the build time. I don't mind doing that at 
all, just wondering is there a good way to not build the static content, 
or would that be the best way?


This is already great by the way, for what I need to it to do - none of 
this is super important though, but if you have any thoughts I'll give 
it another go and see if I can get a more optimized build.


--
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

On Tue, Jul 11, 2023 at 3:28 PM  wrote:

> On 7/11/2023 4:34 PM, George Joseph wrote:
> > On Sat, Jul 8, 2023 at 4:24 PM  > > wrote:
> >
> > Hi, Geroge,
> >  Just had a chance to look at this this afternoon. The
> > instructions
> > for the dynamic doc generation definitely made my head hurt a little
> > bit, but I have a few thoughts after putzing around a little bit.
> >
> >
> > Your head should be much better now. :)
>
> Much better... the A/C repairman just left too, which helps :)
>

I'll bet.  It was over 102F/39C here in Denver yesterday.


>
> >
> > My initial thought was that some of the make targets in the Makefile
> > could be split up a little bit. The version-dynamic target both
> > downloads documentation source and does the actual build of the
> > documentation. They could be split into different targets:
> >
> >   * In my case, I don't want to download the upstream Asterisk
> > documentation, I want to use the local core-en-us.xml, which is a
> > superset of the documentation available upstream.
> >
> >
> > Uhm are you sure??   The core XML document generated during a build
> > doesn't have the xinclude references de-referenced.  I'd be interested
> > to know what you're seeing.
>
> Mm... yes, you're right about that. I remember encountering that
> limitation when I wrote my converter. I planned to do something about
> it, but never did :)
> My core-en_US.xml and full-en_US.xml files are very similar in size so I
> don't think which one I use would make any difference with this.
>
> As far as "what I'm seeing", this is an example of what I get when I
> take my built XML file at the end of compiling and run it through my
> conversion script: https://asterisk.phreaknet.org/
>
> 

>
> I could keep using this, of course, since nothing has changed with the
> XML and there's no Confluence involved, but what you've done with the
> dynamic docs is way better (and the search capability is really nice),
> so I'd like to migrate to that for internal documentation.
>
> How are the includes *supposed* to be handled, by the way i.e. what's
> supposed to dereference the xincludes? Is it one of the Asterisk build
> scripts for the docs piecing everything together, or is it expected that
> whatever consumes the XML files is able to handle those?
>

XML processing is kinda spread out all over
* build_tools/get_documentation.py
* build_tools/make_xml_documentation
* loader.c:load_modules().

TBH, I haven't looked at that stuff in years.  It could probably be
simplified quite a bit.


>
> > There are now facilities in the Makefile to get the dynamic sources
> > from your
> > local system.   In that case, gh is not required. Details in the README.
>
> Found a typo in the new README, seems to be just on that branch so I
> guess I can't submit a PR: "CreteDocs"
>

Only one??   Fixed.



>
> > You don't need to avoid the Makefile.  You can specify where to get
> > the dynamic sources from and which branches to build.  Details in the
> > README.
>
> I'm a little confused about the BRANCHES variable in Makefile.inc. I
> presume this is irrelevant if using a local XML doc? If only because
> there's only one version of Asterisk compiled (and from which the XML
> doc is sourced). It does specifically say if I'm using local sources I
> need separate Makefile.branch.inc's though so I think I'm not
> understanding something here.
>

> I think I understand why the branches are needed - because now it's
> building all the docs for all the versions into the same site. I think
> my point of confusion is the dynamic doc builder only sees an XML file,
> it can't even possibly know what version of Asterisk that's for without
> being told, can it? I was thinking that make BRANCHES=XX just needs to
> match Makefile.XX.inc, but wasn't sure if there's any other significance
> to these values.
>

You're on the right track.  If you want to do a full build for multiple
branches and wanted to use local documentation for each, you'd need a
Makefile..inc  file for each branch whose ASTERISK_XML_FILE
and ASTERISK_ARI_DIR variables point to different sets of source
documentation.  So yes, you'd need a Makefile..inc file for each
entry in BRANCHES that you want to use local documentation for.  If you
wanted to, you _could_ use local documentation for only a subset of
branches and retrieve the rest from the Asterisk nightly job.  The trigger
is whether those 2 variables are defined ro a branch or not.

If you only want to build 1 branch, say 20, with local docs, the solution
is even simpler... Just put those 2 variables directly in Makefile.inc and
set BRANCHES := 20.

Makefile.inc:
ASTERISK_XML_FILE := /core-en_US.xml
ASTERISK_ARI_DIR := /rest-api
BRANCHES := 20

Now you can just run 'make' with no options.


>
> It seems to still be trying to download it for me despite adding the
> includes, though I just set up the includes and followed the
> 

Re: [asterisk-dev] Final Preview: docs.asterisk.org

[asterisk]

On 7/11/2023 4:34 PM, George Joseph wrote:
On Sat, Jul 8, 2023 at 4:24 PM > wrote:


Hi, Geroge,
 Just had a chance to look at this this afternoon. The
instructions
for the dynamic doc generation definitely made my head hurt a little
bit, but I have a few thoughts after putzing around a little bit.


Your head should be much better now. :)


Much better... the A/C repairman just left too, which helps :)



My initial thought was that some of the make targets in the Makefile
could be split up a little bit. The version-dynamic target both
downloads documentation source and does the actual build of the
documentation. They could be split into different targets:

  * In my case, I don't want to download the upstream Asterisk
    documentation, I want to use the local core-en-us.xml, which is a
    superset of the documentation available upstream.


Uhm are you sure??   The core XML document generated during a build 
doesn't have the xinclude references de-referenced.  I'd be interested 
to know what you're seeing.


Mm... yes, you're right about that. I remember encountering that 
limitation when I wrote my converter. I planned to do something about 
it, but never did :)
My core-en_US.xml and full-en_US.xml files are very similar in size so I 
don't think which one I use would make any difference with this.


As far as "what I'm seeing", this is an example of what I get when I 
take my built XML file at the end of compiling and run it through my 
conversion script: https://asterisk.phreaknet.org/


I believe it handles most of the documentation except those 
xinclude/pointer references to other files. It's not fully on par with 
the real docs, but my main use case here was being able to view 
documentation for applications and functions that aren't upstreamed, and 
for that it's sufficed. Also, the parser I wrote is not super robust, an 
unintended benefit of which is occasionally it's caught bugs in the 
xmldocs that have needed to be fixed, that otherwise might have slipped 
through a more lenient parser.


I could keep using this, of course, since nothing has changed with the 
XML and there's no Confluence involved, but what you've done with the 
dynamic docs is way better (and the search capability is really nice), 
so I'd like to migrate to that for internal documentation.


How are the includes *supposed* to be handled, by the way i.e. what's 
supposed to dereference the xincludes? Is it one of the Asterisk build 
scripts for the docs piecing everything together, or is it expected that 
whatever consumes the XML files is able to handle those?


There are now facilities in the Makefile to get the dynamic sources 
from your

local system.   In that case, gh is not required. Details in the README.


Found a typo in the new README, seems to be just on that branch so I 
guess I can't submit a PR: "CreteDocs"




Then again, when you boil it down to that, it seems like it really
comes
down to just:

  * utils/astxml2markdown.py
  * mike deploy

So it seems I'm better off avoiding the makefile and just running the
individual commands needed. I'll end up wrapping it in a script
anyways,
but just wondering if there's anything else about the process here
I've
missed that wouldn't be conducive to that?


You don't need to avoid the Makefile.  You can specify where to get 
the dynamic sources from and which branches to build.  Details in the 
README.


I'm a little confused about the BRANCHES variable in Makefile.inc. I 
presume this is irrelevant if using a local XML doc? If only because 
there's only one version of Asterisk compiled (and from which the XML 
doc is sourced). It does specifically say if I'm using local sources I 
need separate Makefile.branch.inc's though so I think I'm not 
understanding something here.


I think I understand why the branches are needed - because now it's 
building all the docs for all the versions into the same site. I think 
my point of confusion is the dynamic doc builder only sees an XML file, 
it can't even possibly know what version of Asterisk that's for without 
being told, can it? I was thinking that make BRANCHES=XX just needs to 
match Makefile.XX.inc, but wasn't sure if there's any other significance 
to these values.


It seems to still be trying to download it for me despite adding the 
includes, though I just set up the includes and followed the 
instructions, haven't dug much deeper


root@debian11:/usr/src/documentation# nano Makefile.inc
root@debian11:/usr/src/documentation# nano Makefile.20.inc
root@debian11:/usr/src/documentation# make BRANCHES=20
Finding last CreateDocs job
/usr/bin/bash: line 1: gh: command not found
Setting Up Static Documentation
  Copying to temp build
  Applying link transformations
Building branch 20
Finding last CreateDocs job
/usr/bin/bash: line 1: gh: command not found
Creating ./temp/build-20
Setting Up Core 

Re: [asterisk-dev] Final Preview: docs.asterisk.org

[George Joseph]

Comments in line ...

On Sat, Jul 8, 2023 at 4:24 PM  wrote:

> Hi, Geroge,
>  Just had a chance to look at this this afternoon. The instructions
> for the dynamic doc generation definitely made my head hurt a little
> bit, but I have a few thoughts after putzing around a little bit.
>

Your head should be much better now. :)


>
> My initial thought was that some of the make targets in the Makefile
> could be split up a little bit. The version-dynamic target both
> downloads documentation source and does the actual build of the
> documentation. They could be split into different targets:
>
>   * In my case, I don't want to download the upstream Asterisk
> documentation, I want to use the local core-en-us.xml, which is a
> superset of the documentation available upstream.
>

Uhm are you sure??   The core XML document generated during a build doesn't
have the xinclude references de-referenced.  I'd be interested to know what
you're seeing.


>   * Since I'm not downloading the docs, I don't think I need the "gh"
> tool, and so it doesn't need to be installed for purely generating
> documentation. (Also, could be documented as a pre-req, if doing the
> download step)
>

There are now facilities in the Makefile to get the dynamic sources from
your
local system.   In that case, gh is not required.  Details in the README.


>
> Then again, when you boil it down to that, it seems like it really comes
> down to just:
>
>   * utils/astxml2markdown.py
>   * mike deploy
>
> So it seems I'm better off avoiding the makefile and just running the
> individual commands needed. I'll end up wrapping it in a script anyways,
> but just wondering if there's anything else about the process here I've
> missed that wouldn't be conducive to that?
>

You don't need to avoid the Makefile.  You can specify where to get the
dynamic sources from and which branches to build.  Details in the README.


>
> In particular, it doesn't seem that finagling with Git repositories is
> necessary at all to build the dynamic docs. I was able to get it to work
> with just this:
>

No more git repo finagling.


>
> git clone https://github.com/asterisk/documentation.git --depth 1
> cd documentation
> pip3 install -r requirements.txt
> mv docs/favicon.ico docs/index.md .
> rm -rf docs/*
> mv favicon.ico index.md docs
> utils/astxml2markdown.py
> --file=/usr/src/asterisk-20.3.0/doc/core-en_US.xml
> --xslt=utils/astxml2markdown.xslt --directory=docs/ --branch=20
> --version=20.3.0
> mike deploy -F mkdocs.yml 20
> rm -rf /var/www/html/asterisk && mv site /var/www/html/asterisk
> cd .. && rm -rf documentation
>
> It seems to work really well. There were just a couple surprises or
> annoying aspects:
>
>   * Even with --depth 1, the documentation repo takes a hot minute to
> clone, due to all the large PDF artifacts in it, though a tarball of
> the repo wouldn't help either if it came with all the static
> artifacts anyways. Could probably work around that by cloning it
> using svn instead of git, but I was too lazy to do that today.
>

No longer needed.


>   * For just turning markdown into HTML, mike is pretty slow, it takes
> over half a minute just for the dynamic docs (compared to ~1 second
> for my previous method, though that was from the original XML to
> HTML, not from intermediate markdown)
>

mike has bene eliminated.


>   * Most significantly, the webpages are *huge*. Even just the dynamic
> docs are a whopping 228 MB. On average, a documentation page is
> almost 250 KB (compared to 1.2 MB the old way for all the
> applications, functions, AMI/AGI, and configs on a single webpage -
> granted it's not a fair comparison since the menu and what not isn't
> repeated that way). Taking a look at the page source of an
> application[1], much of the page is whitespace. I know that docs
> hosted on GitHub don't need to worry about disk consumption, but for
> folks building the docs themselves, I think it might be worth trying
> to clean this a little bit. Bloated webpages are obviously also
> going to be slower to load as well.
>

File sizes have been significantly reduced by updating mkdocs and using the
new navigation.prune option.  I tried removing all of the extra whitespace
but after the prune option was applied it made very little difference
overall.  We can keep looking at it.


>
> I haven't yet figured out what's introducing all the extraneous
> whitespace. The markdown files seem okay, but things seem to blow up
> somewhere in the middle. Ideally we could prevent it from happening in
> the first place, but if not, then maybe some fancy recursive
> post-processing could strip it all out.
>
> [1] https://docs.asterisk.org/20/_Dialplan_Applications/ADSIProg/
>
>
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or 

Re: [asterisk-dev] Final Preview: docs.asterisk.org

[George Joseph]

On Mon, Jul 10, 2023 at 1:06 PM  wrote:

> On 7/10/2023 10:09 AM, George Joseph wrote:
> > I'm digesting this.  It may be a while. :)
>
> Sorry, didn't mean to dump a novel on you there. Let me know if there's
> anything I should clarify.
>

No worries.  I've managed to eliminate 'mike' completely and
restructured things so the left nav bar looks much like the original wiki
with an entry for each branch's API documentation.  The site is also now
built as one complete site and it's much easier to just build the static
docs then add in the dynamic docs.  The makefile also has a dependency on
./temp/build-XX/source/asterisk-docs.xml so if it already exists (say if
you pre-copied core-en_US.xml to it) it won't do the download and extract.
 I just need to update the README and I'll push this up as a new branch so
you can take a look without disturbing the existing stuff.


>
> On another note, after a couple months of being in the GitHub workflow,
> here's another suggestion for improvement, if it's an easy change to make:
>
> The workflow that reminds people to post a cherry pick comment is
> obviously helpful. However, I've noticed that this runs on issues,
> regardless of whether or not a comment already exists on the issue for
> cherry picks. I usually post that comment before the bot kicks in, but
> it comments nonetheless. GitHub sends a voluminous amount of email,
> which isn't necessarily bad per se, but at this point, I find I've been
> conditioned to ignore these emails and notices, though every now and
> then I will forget and then it ends up being harder to keep track of due
> to all the "noise" mixed in.
>
>
Actually, I thought I did this already but it must have escaped my mind.
I'll get to it this week.


> Instead of "crying wolf" all the time, would it be possible to have
> these comment on issues only if there isn't already an existing comment?
> If that wouldn't be trivial to do, no biggie, just one (minor) painpoint
> I've noticed.
>
> Other than the well known problem of the tests constantly failing to the
> point where I'm just ignoring test failures as well, no other issues
> I've noticed; everything has been pretty smooth. Kudos to George and
> everyone else for making this a really smooth transition.
>

Thanks!


>
>   NA
>
-- 
_
-- 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] Final Preview: docs.asterisk.org

[asterisk]

On 7/10/2023 10:09 AM, George Joseph wrote:

I'm digesting this.  It may be a while. :)


Sorry, didn't mean to dump a novel on you there. Let me know if there's 
anything I should clarify.


On another note, after a couple months of being in the GitHub workflow, 
here's another suggestion for improvement, if it's an easy change to make:


The workflow that reminds people to post a cherry pick comment is 
obviously helpful. However, I've noticed that this runs on issues, 
regardless of whether or not a comment already exists on the issue for 
cherry picks. I usually post that comment before the bot kicks in, but 
it comments nonetheless. GitHub sends a voluminous amount of email, 
which isn't necessarily bad per se, but at this point, I find I've been 
conditioned to ignore these emails and notices, though every now and 
then I will forget and then it ends up being harder to keep track of due 
to all the "noise" mixed in.


Instead of "crying wolf" all the time, would it be possible to have 
these comment on issues only if there isn't already an existing comment? 
If that wouldn't be trivial to do, no biggie, just one (minor) painpoint 
I've noticed.


Other than the well known problem of the tests constantly failing to the 
point where I'm just ignoring test failures as well, no other issues 
I've noticed; everything has been pretty smooth. Kudos to George and 
everyone else for making this a really smooth transition.


 NA

--
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

I'm digesting this.  It may be a while. :)


On Sat, Jul 8, 2023 at 4:24 PM  wrote:

> On 6/29/2023 3:14 PM, George Joseph wrote:
> > I think we're at a point where the new documentation site can go
> > live.  The dynamic documentation is integrated and the README file has
> > been expanded greatly with information on how the site is built and
> > how you can build it yourself.
>
> Hi, Geroge,
>  Just had a chance to look at this this afternoon. The instructions
> for the dynamic doc generation definitely made my head hurt a little
> bit, but I have a few thoughts after putzing around a little bit.
>
> My initial thought was that some of the make targets in the Makefile
> could be split up a little bit. The version-dynamic target both
> downloads documentation source and does the actual build of the
> documentation. They could be split into different targets:
>
>   * In my case, I don't want to download the upstream Asterisk
> documentation, I want to use the local core-en-us.xml, which is a
> superset of the documentation available upstream.
>   * Since I'm not downloading the docs, I don't think I need the "gh"
> tool, and so it doesn't need to be installed for purely generating
> documentation. (Also, could be documented as a pre-req, if doing the
> download step)
>
> Then again, when you boil it down to that, it seems like it really comes
> down to just:
>
>   * utils/astxml2markdown.py
>   * mike deploy
>
> So it seems I'm better off avoiding the makefile and just running the
> individual commands needed. I'll end up wrapping it in a script anyways,
> but just wondering if there's anything else about the process here I've
> missed that wouldn't be conducive to that?
>
> In particular, it doesn't seem that finagling with Git repositories is
> necessary at all to build the dynamic docs. I was able to get it to work
> with just this:
>
> git clone https://github.com/asterisk/documentation.git --depth 1
> cd documentation
> pip3 install -r requirements.txt
> mv docs/favicon.ico docs/index.md .
> rm -rf docs/*
> mv favicon.ico index.md docs
> utils/astxml2markdown.py
> --file=/usr/src/asterisk-20.3.0/doc/core-en_US.xml
> --xslt=utils/astxml2markdown.xslt --directory=docs/ --branch=20
> --version=20.3.0
> mike deploy -F mkdocs.yml 20
> rm -rf /var/www/html/asterisk && mv site /var/www/html/asterisk
> cd .. && rm -rf documentation
>
> It seems to work really well. There were just a couple surprises or
> annoying aspects:
>
>   * Even with --depth 1, the documentation repo takes a hot minute to
> clone, due to all the large PDF artifacts in it, though a tarball of
> the repo wouldn't help either if it came with all the static
> artifacts anyways. Could probably work around that by cloning it
> using svn instead of git, but I was too lazy to do that today.
>   * For just turning markdown into HTML, mike is pretty slow, it takes
> over half a minute just for the dynamic docs (compared to ~1 second
> for my previous method, though that was from the original XML to
> HTML, not from intermediate markdown)
>   * Most significantly, the webpages are *huge*. Even just the dynamic
> docs are a whopping 228 MB. On average, a documentation page is
> almost 250 KB (compared to 1.2 MB the old way for all the
> applications, functions, AMI/AGI, and configs on a single webpage -
> granted it's not a fair comparison since the menu and what not isn't
> repeated that way). Taking a look at the page source of an
> application[1], much of the page is whitespace. I know that docs
> hosted on GitHub don't need to worry about disk consumption, but for
> folks building the docs themselves, I think it might be worth trying
> to clean this a little bit. Bloated webpages are obviously also
> going to be slower to load as well.
>
> I haven't yet figured out what's introducing all the extraneous
> whitespace. The markdown files seem okay, but things seem to blow up
> somewhere in the middle. Ideally we could prevent it from happening in
> the first place, but if not, then maybe some fancy recursive
> post-processing could strip it all out.
>
> [1] https://docs.asterisk.org/20/_Dialplan_Applications/ADSIProg/
>
>
-- 
_
-- 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] Final Preview: docs.asterisk.org

[asterisk]

On 6/29/2023 3:14 PM, George Joseph wrote:
I think we're at a point where the new documentation site can go 
live.  The dynamic documentation is integrated and the README file has 
been expanded greatly with information on how the site is built and 
how you can build it yourself.


Hi, Geroge,
    Just had a chance to look at this this afternoon. The instructions 
for the dynamic doc generation definitely made my head hurt a little 
bit, but I have a few thoughts after putzing around a little bit.


My initial thought was that some of the make targets in the Makefile 
could be split up a little bit. The version-dynamic target both 
downloads documentation source and does the actual build of the 
documentation. They could be split into different targets:


 * In my case, I don't want to download the upstream Asterisk
   documentation, I want to use the local core-en-us.xml, which is a
   superset of the documentation available upstream.
 * Since I'm not downloading the docs, I don't think I need the "gh"
   tool, and so it doesn't need to be installed for purely generating
   documentation. (Also, could be documented as a pre-req, if doing the
   download step)

Then again, when you boil it down to that, it seems like it really comes 
down to just:


 * utils/astxml2markdown.py
 * mike deploy

So it seems I'm better off avoiding the makefile and just running the 
individual commands needed. I'll end up wrapping it in a script anyways, 
but just wondering if there's anything else about the process here I've 
missed that wouldn't be conducive to that?


In particular, it doesn't seem that finagling with Git repositories is 
necessary at all to build the dynamic docs. I was able to get it to work 
with just this:


git clone https://github.com/asterisk/documentation.git --depth 1
cd documentation
pip3 install -r requirements.txt
mv docs/favicon.ico docs/index.md .
rm -rf docs/*
mv favicon.ico index.md docs
utils/astxml2markdown.py 
--file=/usr/src/asterisk-20.3.0/doc/core-en_US.xml 
--xslt=utils/astxml2markdown.xslt --directory=docs/ --branch=20 
--version=20.3.0

mike deploy -F mkdocs.yml 20
rm -rf /var/www/html/asterisk && mv site /var/www/html/asterisk
cd .. && rm -rf documentation

It seems to work really well. There were just a couple surprises or 
annoying aspects:


 * Even with --depth 1, the documentation repo takes a hot minute to
   clone, due to all the large PDF artifacts in it, though a tarball of
   the repo wouldn't help either if it came with all the static
   artifacts anyways. Could probably work around that by cloning it
   using svn instead of git, but I was too lazy to do that today.
 * For just turning markdown into HTML, mike is pretty slow, it takes
   over half a minute just for the dynamic docs (compared to ~1 second
   for my previous method, though that was from the original XML to
   HTML, not from intermediate markdown)
 * Most significantly, the webpages are *huge*. Even just the dynamic
   docs are a whopping 228 MB. On average, a documentation page is
   almost 250 KB (compared to 1.2 MB the old way for all the
   applications, functions, AMI/AGI, and configs on a single webpage -
   granted it's not a fair comparison since the menu and what not isn't
   repeated that way). Taking a look at the page source of an
   application[1], much of the page is whitespace. I know that docs
   hosted on GitHub don't need to worry about disk consumption, but for
   folks building the docs themselves, I think it might be worth trying
   to clean this a little bit. Bloated webpages are obviously also
   going to be slower to load as well.

I haven't yet figured out what's introducing all the extraneous 
whitespace. The markdown files seem okay, but things seem to blow up 
somewhere in the middle. Ideally we could prevent it from happening in 
the first place, but if not, then maybe some fancy recursive 
post-processing could strip it all out.


[1] https://docs.asterisk.org/20/_Dialplan_Applications/ADSIProg/


--
_
-- 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] Final Preview: docs.asterisk.org

[Andrew Latham]

Thanks George, That is what was really needed (I face palmed at how obvious
that was)

On Fri, Jun 30, 2023 at 10:26 AM George Joseph  wrote:

>
>
> On Fri, Jun 30, 2023 at 9:36 AM Andrew Latham  wrote:
>
>> George
>>
>> I just had an idea. We could disable the github plugin by not setting a
>> repo and then just add the links to a custom footer or `About` page. Just a
>> thought
>>
>
> Actually, changing that plugin to point to the actual asterisk repo makes
> more sense and seems to show the correct release, number of stars and forks.
>
>
>>
>> On Fri, Jun 30, 2023 at 9:33 AM Andrew Latham  wrote:
>>
>>> Ack, thanks George
>>>
>>> * As best I can tell in the JS [1] it needs a release to generate the
>>> version. I do agree with you that there is no real need for releases.
>>> However to enable the JS to work a release may be required.
>>> * I can see how the double Asterisk logos at the bottom would be
>>> confusing. I just get a cringe factor when I see the wordpress logo and
>>> that is just a me thing.
>>>
>>> 1.
>>> https://github.com/squidfunk/mkdocs-material/blob/55fb2e335e04df5b206f2058ba4b706d930b496f/src/assets/javascripts/components/source/facts/github/index.ts#L67C1-L75
>>>
>>> On Fri, Jun 30, 2023 at 5:23 AM George Joseph 
>>> wrote:
>>>


 On Thu, Jun 29, 2023 at 2:06 PM Andrew Latham 
 wrote:

> Good Work George and crew. It looks really good, it is snappy, looks
> nice on mobile.
>

 Thanks!


>
> All boxes checked!!!
>
> Nits
>
> 1. I get a 404 on
> https://api.github.com/repos/asterisk/documentation/releases/latest
> because there is no release yet I guess
>

 Correct.  We're not going to do actual releases here because the site
 is live off the gh-pages branch and whatever is in the main branch.  Do you
 think we need to?


> 2. I am thinking the Asterisk Logo would be good at the bottom instead
> of the wordpress icon for the blog. Thinking outloud
>

 Then it'd look no different than the website icon.  Maybe we can make
 the background asterisk-orange or something but keep the wordpress logo.


>
> On Thu, Jun 29, 2023 at 1:14 PM George Joseph 
> wrote:
>
>> I think we're at a point where the new documentation site can go
>> live.  The dynamic documentation is integrated and the README file has 
>> been
>> expanded greatly with information on how the site is built and how you 
>> can
>> build it yourself.
>>
>> Please give it a final look:  https://docs.asterisk.org
>>
>> --
>> 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 -
>>>
>>
>>
>> --
>> - 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] Final Preview: docs.asterisk.org

[George Joseph]

On Fri, Jun 30, 2023 at 9:36 AM Andrew Latham  wrote:

> George
>
> I just had an idea. We could disable the github plugin by not setting a
> repo and then just add the links to a custom footer or `About` page. Just a
> thought
>

Actually, changing that plugin to point to the actual asterisk repo makes
more sense and seems to show the correct release, number of stars and forks.


>
> On Fri, Jun 30, 2023 at 9:33 AM Andrew Latham  wrote:
>
>> Ack, thanks George
>>
>> * As best I can tell in the JS [1] it needs a release to generate the
>> version. I do agree with you that there is no real need for releases.
>> However to enable the JS to work a release may be required.
>> * I can see how the double Asterisk logos at the bottom would be
>> confusing. I just get a cringe factor when I see the wordpress logo and
>> that is just a me thing.
>>
>> 1.
>> https://github.com/squidfunk/mkdocs-material/blob/55fb2e335e04df5b206f2058ba4b706d930b496f/src/assets/javascripts/components/source/facts/github/index.ts#L67C1-L75
>>
>> On Fri, Jun 30, 2023 at 5:23 AM George Joseph 
>> wrote:
>>
>>>
>>>
>>> On Thu, Jun 29, 2023 at 2:06 PM Andrew Latham  wrote:
>>>
 Good Work George and crew. It looks really good, it is snappy, looks
 nice on mobile.

>>>
>>> Thanks!
>>>
>>>

 All boxes checked!!!

 Nits

 1. I get a 404 on
 https://api.github.com/repos/asterisk/documentation/releases/latest
 because there is no release yet I guess

>>>
>>> Correct.  We're not going to do actual releases here because the site is
>>> live off the gh-pages branch and whatever is in the main branch.  Do you
>>> think we need to?
>>>
>>>
 2. I am thinking the Asterisk Logo would be good at the bottom instead
 of the wordpress icon for the blog. Thinking outloud

>>>
>>> Then it'd look no different than the website icon.  Maybe we can make
>>> the background asterisk-orange or something but keep the wordpress logo.
>>>
>>>

 On Thu, Jun 29, 2023 at 1:14 PM George Joseph 
 wrote:

> I think we're at a point where the new documentation site can go
> live.  The dynamic documentation is integrated and the README file has 
> been
> expanded greatly with information on how the site is built and how you can
> build it yourself.
>
> Please give it a final look:  https://docs.asterisk.org
>
> --
> 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 -
>>
>
>
> --
> - 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] Final Preview: docs.asterisk.org

[Andrew Latham]

George

I just had an idea. We could disable the github plugin by not setting a
repo and then just add the links to a custom footer or `About` page. Just a
thought

On Fri, Jun 30, 2023 at 9:33 AM Andrew Latham  wrote:

> Ack, thanks George
>
> * As best I can tell in the JS [1] it needs a release to generate the
> version. I do agree with you that there is no real need for releases.
> However to enable the JS to work a release may be required.
> * I can see how the double Asterisk logos at the bottom would be
> confusing. I just get a cringe factor when I see the wordpress logo and
> that is just a me thing.
>
> 1.
> https://github.com/squidfunk/mkdocs-material/blob/55fb2e335e04df5b206f2058ba4b706d930b496f/src/assets/javascripts/components/source/facts/github/index.ts#L67C1-L75
>
> On Fri, Jun 30, 2023 at 5:23 AM George Joseph  wrote:
>
>>
>>
>> On Thu, Jun 29, 2023 at 2:06 PM Andrew Latham  wrote:
>>
>>> Good Work George and crew. It looks really good, it is snappy, looks
>>> nice on mobile.
>>>
>>
>> Thanks!
>>
>>
>>>
>>> All boxes checked!!!
>>>
>>> Nits
>>>
>>> 1. I get a 404 on
>>> https://api.github.com/repos/asterisk/documentation/releases/latest
>>> because there is no release yet I guess
>>>
>>
>> Correct.  We're not going to do actual releases here because the site is
>> live off the gh-pages branch and whatever is in the main branch.  Do you
>> think we need to?
>>
>>
>>> 2. I am thinking the Asterisk Logo would be good at the bottom instead
>>> of the wordpress icon for the blog. Thinking outloud
>>>
>>
>> Then it'd look no different than the website icon.  Maybe we can make the
>> background asterisk-orange or something but keep the wordpress logo.
>>
>>
>>>
>>> On Thu, Jun 29, 2023 at 1:14 PM George Joseph 
>>> wrote:
>>>
 I think we're at a point where the new documentation site can go live.
 The dynamic documentation is integrated and the README file has been
 expanded greatly with information on how the site is built and how you can
 build it yourself.

 Please give it a final look:  https://docs.asterisk.org

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


-- 
- 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] Final Preview: docs.asterisk.org

[Andrew Latham]

Ack, thanks George

* As best I can tell in the JS [1] it needs a release to generate the
version. I do agree with you that there is no real need for releases.
However to enable the JS to work a release may be required.
* I can see how the double Asterisk logos at the bottom would be confusing.
I just get a cringe factor when I see the wordpress logo and that is just a
me thing.

1.
https://github.com/squidfunk/mkdocs-material/blob/55fb2e335e04df5b206f2058ba4b706d930b496f/src/assets/javascripts/components/source/facts/github/index.ts#L67C1-L75

On Fri, Jun 30, 2023 at 5:23 AM George Joseph  wrote:

>
>
> On Thu, Jun 29, 2023 at 2:06 PM Andrew Latham  wrote:
>
>> Good Work George and crew. It looks really good, it is snappy, looks nice
>> on mobile.
>>
>
> Thanks!
>
>
>>
>> All boxes checked!!!
>>
>> Nits
>>
>> 1. I get a 404 on
>> https://api.github.com/repos/asterisk/documentation/releases/latest
>> because there is no release yet I guess
>>
>
> Correct.  We're not going to do actual releases here because the site is
> live off the gh-pages branch and whatever is in the main branch.  Do you
> think we need to?
>
>
>> 2. I am thinking the Asterisk Logo would be good at the bottom instead of
>> the wordpress icon for the blog. Thinking outloud
>>
>
> Then it'd look no different than the website icon.  Maybe we can make the
> background asterisk-orange or something but keep the wordpress logo.
>
>
>>
>> On Thu, Jun 29, 2023 at 1:14 PM George Joseph 
>> wrote:
>>
>>> I think we're at a point where the new documentation site can go live.
>>> The dynamic documentation is integrated and the README file has been
>>> expanded greatly with information on how the site is built and how you can
>>> build it yourself.
>>>
>>> Please give it a final look:  https://docs.asterisk.org
>>>
>>> --
>>> 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] Final Preview: docs.asterisk.org

[Shloime Rosenblum]

[image: image.png]

On Fri, Jun 30, 2023 at 10:37 AM George Joseph  wrote:

>
>
> On Fri, Jun 30, 2023 at 8:30 AM Shloime Rosenblum <
> shloimerosenb...@gmail.com> wrote:
>
>> Is the double bullets on purpose?
>>
>
> Nope.  I thought I fixed those.  Added to the list.
>
>
>>
>> [image: image.png]
>>
>> On Fri, Jun 30, 2023 at 10:03 AM Niklas Larsson  wrote:
>>
>>> Hi,
>>>
>>> On
>>> https://docs.asterisk.org/20/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/
>>> the link to "Core res_pjsip configuration options" points to
>>> https://docs.asterisk.org/latest/Asterisk-12-Configuration_res_pjsip -
>>> and that is a 404
>>>
>>> /niklas
>>>
>>> On 2023-06-29 21:14, George Joseph wrote:
>>>
>>> I think we're at a point where the new documentation site can go live.
>>> The dynamic documentation is integrated and the README file has been
>>> expanded greatly with information on how the site is built and how you can
>>> build it yourself.
>>>
>>> Please give it a final look:  https://docs.asterisk.org
>>>
>>> --
>>> 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
>>
>> --
>> _
>> -- 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
-- 
_
-- 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] Final Preview: docs.asterisk.org

[George Joseph]

On Fri, Jun 30, 2023 at 8:30 AM Shloime Rosenblum <
shloimerosenb...@gmail.com> wrote:

> Is the double bullets on purpose?
>

Nope.  I thought I fixed those.  Added to the list.


>
> [image: image.png]
>
> On Fri, Jun 30, 2023 at 10:03 AM Niklas Larsson  wrote:
>
>> Hi,
>>
>> On
>> https://docs.asterisk.org/20/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/
>> the link to "Core res_pjsip configuration options" points to
>> https://docs.asterisk.org/latest/Asterisk-12-Configuration_res_pjsip -
>> and that is a 404
>>
>> /niklas
>>
>> On 2023-06-29 21:14, George Joseph wrote:
>>
>> I think we're at a point where the new documentation site can go live.
>> The dynamic documentation is integrated and the README file has been
>> expanded greatly with information on how the site is built and how you can
>> build it yourself.
>>
>> Please give it a final look:  https://docs.asterisk.org
>>
>> --
>> 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
>
> --
> _
> -- 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] Final Preview: docs.asterisk.org

[George Joseph]

On Fri, Jun 30, 2023 at 8:03 AM Niklas Larsson  wrote:

> Hi,
>
> On
> https://docs.asterisk.org/20/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/
> the link to "Core res_pjsip configuration options" points to
> https://docs.asterisk.org/latest/Asterisk-12-Configuration_res_pjsip -
> and that is a 404
>
>
Yeah, there are a bunch of those that still need to be fixed.
Adding to the list for this afternoon.



> /niklas
>
> On 2023-06-29 21:14, George Joseph wrote:
>
> I think we're at a point where the new documentation site can go live.
> The dynamic documentation is integrated and the README file has been
> expanded greatly with information on how the site is built and how you can
> build it yourself.
>
> Please give it a final look:  https://docs.asterisk.org
>
> --
> 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
-- 
_
-- 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] Final Preview: docs.asterisk.org

[Shloime Rosenblum]

Is the double bullets on purpose?

[image: image.png]

On Fri, Jun 30, 2023 at 10:03 AM Niklas Larsson  wrote:

> Hi,
>
> On
> https://docs.asterisk.org/20/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/
> the link to "Core res_pjsip configuration options" points to
> https://docs.asterisk.org/latest/Asterisk-12-Configuration_res_pjsip -
> and that is a 404
>
> /niklas
>
> On 2023-06-29 21:14, George Joseph wrote:
>
> I think we're at a point where the new documentation site can go live.
> The dynamic documentation is integrated and the README file has been
> expanded greatly with information on how the site is built and how you can
> build it yourself.
>
> Please give it a final look:  https://docs.asterisk.org
>
> --
> 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
-- 
_
-- 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] Final Preview: docs.asterisk.org

[Niklas Larsson]

Hi,

On 
https://docs.asterisk.org/20/Configuration/Channel-Drivers/SIP/Configuring-res_pjsip/ 
the link to "Core res_pjsip configuration options" points to 
https://docs.asterisk.org/latest/Asterisk-12-Configuration_res_pjsip - 
and that is a 404


/niklas

On 2023-06-29 21:14, George Joseph wrote:
I think we're at a point where the new documentation site can go 
live.  The dynamic documentation is integrated and the README file has 
been expanded greatly with information on how the site is built and 
how you can build it yourself.


Please give it a final look: https://docs.asterisk.org

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

Re: [asterisk-dev] Final Preview: docs.asterisk.org

[Joshua C. Colp]

On Fri, Jun 30, 2023 at 8:52 AM Olivier  wrote:

> IMHO, having per-Asterisk-version doc is very useful feature of
> current wiki for those maintening an heterogeneous set of Asterisk
> instances or wanting to study differences between versions.
>

The Asterisk Latest (20) at the top of the docs site is a menu that can be
used to switch between different versions and display the specific
reference documentation for it.

-- 
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] Final Preview: docs.asterisk.org

[George Joseph]

On Thu, Jun 29, 2023 at 2:07 PM Andrew Latham  wrote:

> More testing, I notice the logo is missing on the versions in the top left
> corner eg https://docs.asterisk.org/19/
>

Oh yeah.  I probably need to copy it somewhere.  I'll do that later today.


>
> On Thu, Jun 29, 2023 at 2:05 PM Andrew Latham  wrote:
>
>> Good Work George and crew. It looks really good, it is snappy, looks nice
>> on mobile.
>>
>> All boxes checked!!!
>>
>> Nits
>>
>> 1. I get a 404 on
>> https://api.github.com/repos/asterisk/documentation/releases/latest
>> because there is no release yet I guess
>> 2. I am thinking the Asterisk Logo would be good at the bottom instead of
>> the wordpress icon for the blog. Thinking outloud
>>
>> On Thu, Jun 29, 2023 at 1:14 PM George Joseph 
>> wrote:
>>
>>> I think we're at a point where the new documentation site can go live.
>>> The dynamic documentation is integrated and the README file has been
>>> expanded greatly with information on how the site is built and how you can
>>> build it yourself.
>>>
>>> Please give it a final look:  https://docs.asterisk.org
>>>
>>> --
>>> 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 -
>>
>
>
> --
> - 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] Final Preview: docs.asterisk.org

[George Joseph]

On Thu, Jun 29, 2023 at 2:06 PM Andrew Latham  wrote:

> Good Work George and crew. It looks really good, it is snappy, looks nice
> on mobile.
>

Thanks!


>
> All boxes checked!!!
>
> Nits
>
> 1. I get a 404 on
> https://api.github.com/repos/asterisk/documentation/releases/latest
> because there is no release yet I guess
>

Correct.  We're not going to do actual releases here because the site is
live off the gh-pages branch and whatever is in the main branch.  Do you
think we need to?


> 2. I am thinking the Asterisk Logo would be good at the bottom instead of
> the wordpress icon for the blog. Thinking outloud
>

Then it'd look no different than the website icon.  Maybe we can make the
background asterisk-orange or something but keep the wordpress logo.


>
> On Thu, Jun 29, 2023 at 1:14 PM George Joseph  wrote:
>
>> I think we're at a point where the new documentation site can go live.
>> The dynamic documentation is integrated and the README file has been
>> expanded greatly with information on how the site is built and how you can
>> build it yourself.
>>
>> Please give it a final look:  https://docs.asterisk.org
>>
>> --
>> 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] Final Preview: docs.asterisk.org

[Andrew Latham]

More testing, I notice the logo is missing on the versions in the top left
corner eg https://docs.asterisk.org/19/

On Thu, Jun 29, 2023 at 2:05 PM Andrew Latham  wrote:

> Good Work George and crew. It looks really good, it is snappy, looks nice
> on mobile.
>
> All boxes checked!!!
>
> Nits
>
> 1. I get a 404 on
> https://api.github.com/repos/asterisk/documentation/releases/latest
> because there is no release yet I guess
> 2. I am thinking the Asterisk Logo would be good at the bottom instead of
> the wordpress icon for the blog. Thinking outloud
>
> On Thu, Jun 29, 2023 at 1:14 PM George Joseph  wrote:
>
>> I think we're at a point where the new documentation site can go live.
>> The dynamic documentation is integrated and the README file has been
>> expanded greatly with information on how the site is built and how you can
>> build it yourself.
>>
>> Please give it a final look:  https://docs.asterisk.org
>>
>> --
>> 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 -
>


-- 
- 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] Final Preview: docs.asterisk.org

[Andrew Latham]

Good Work George and crew. It looks really good, it is snappy, looks nice
on mobile.

All boxes checked!!!

Nits

1. I get a 404 on
https://api.github.com/repos/asterisk/documentation/releases/latest because
there is no release yet I guess
2. I am thinking the Asterisk Logo would be good at the bottom instead of
the wordpress icon for the blog. Thinking outloud

On Thu, Jun 29, 2023 at 1:14 PM George Joseph  wrote:

> I think we're at a point where the new documentation site can go live.
> The dynamic documentation is integrated and the README file has been
> expanded greatly with information on how the site is built and how you can
> build it yourself.
>
> Please give it a final look:  https://docs.asterisk.org
>
> --
> 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