[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 := <path>/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 at 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.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20230724/36aeb899/attachment.html>