You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@trafficserver.apache.org by Igor Galić <ig...@apache.org> on 2013/05/05 01:03:26 UTC
Moving the Documentation
Hi folks,
as those of you follow the commits@ list close may have noticed
we have pushed a branch called sphinx-docs to our git repository.
The contents of which are the full trunk documentation of the admin
Guide and the SDK docs. Our intent is to move the documentation
into the source tree so we have it in *one* place, making it easier
for developers to update the documentation at the same time.
It would also mean to move away from ASF CMS system which already
took such pains to implement. There are numerous reasons for this.
The most prevalent is that we no longer wish to write and maintain
our own code to do things that existing documentation systems do
much better.
Sphinx is such a system, and even though the current state of the
docs is incomplete, after installing you can issue a simple
make html
or, for Leif, a make epub ;) and you will build the complete
documentation tree in a nice looking, publishable format.
We'll need to take some steps to get there, so if you think that
we're going in a bad direction I encourage you to speak up *now*!
I also encourage you to provide patches or other forms of help,
if you think that what we're doing is good or worthwhile (:
Thank you,
Igor for the Apache Traffic Server Team
Re: Moving the Documentation
Posted by James Peach <jp...@apache.org>.
On May 4, 2013, at 4:03 PM, Igor Galić <ig...@apache.org> wrote:
>
> Hi folks,
>
> as those of you follow the commits@ list close may have noticed
> we have pushed a branch called sphinx-docs to our git repository.
>
> The contents of which are the full trunk documentation of the admin
> Guide and the SDK docs. Our intent is to move the documentation
> into the source tree so we have it in *one* place, making it easier
> for developers to update the documentation at the same time.
>
> It would also mean to move away from ASF CMS system which already
> took such pains to implement. There are numerous reasons for this.
> The most prevalent is that we no longer wish to write and maintain
> our own code to do things that existing documentation systems do
> much better.
>
> Sphinx is such a system, and even though the current state of the
> docs is incomplete, after installing you can issue a simple
>
> make html
I took it for a quick spin and the output was quite promising.
+1
>
> or, for Leif, a make epub ;) and you will build the complete
> documentation tree in a nice looking, publishable format.
>
> We'll need to take some steps to get there, so if you think that
> we're going in a bad direction I encourage you to speak up *now*!
>
> I also encourage you to provide patches or other forms of help,
> if you think that what we're doing is good or worthwhile (:
>
>
> Thank you,
>
> Igor for the Apache Traffic Server Team
Re: Moving the Documentation
Posted by "G. T. Stresen-Reuter" <te...@gmail.com>.
On May 5, 2013, at 12:03 AM, Igor Galić wrote:
> Our intent is to move the documentation
> into the source tree so we have it in *one* place, making it easier
> for developers to update the documentation at the same time.
+1
I would offer to help, but I would be lying to you and to myself if I pretended to actually have time to do anything more than read this list.
That said, this seems like a good move (as a novice user, I found the existing documentation to be helpful, but a little hard to find the answers I was looking for).
Sincerely,
Ted Stresen-Reuter
Re: Moving the Documentation
Posted by James Peach <jp...@apache.org>.
On May 4, 2013, at 4:03 PM, Igor Galić <ig...@apache.org> wrote:
>
> Hi folks,
>
> as those of you follow the commits@ list close may have noticed
> we have pushed a branch called sphinx-docs to our git repository.
>
> The contents of which are the full trunk documentation of the admin
> Guide and the SDK docs. Our intent is to move the documentation
> into the source tree so we have it in *one* place, making it easier
> for developers to update the documentation at the same time.
>
> It would also mean to move away from ASF CMS system which already
> took such pains to implement. There are numerous reasons for this.
> The most prevalent is that we no longer wish to write and maintain
> our own code to do things that existing documentation systems do
> much better.
>
> Sphinx is such a system, and even though the current state of the
> docs is incomplete, after installing you can issue a simple
>
> make html
I took it for a quick spin and the output was quite promising.
+1
>
> or, for Leif, a make epub ;) and you will build the complete
> documentation tree in a nice looking, publishable format.
>
> We'll need to take some steps to get there, so if you think that
> we're going in a bad direction I encourage you to speak up *now*!
>
> I also encourage you to provide patches or other forms of help,
> if you think that what we're doing is good or worthwhile (:
>
>
> Thank you,
>
> Igor for the Apache Traffic Server Team
Re: Moving the Documentation
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
> Hmmmm, well, I was trying to keep that link from the general mailing
> list ...
>
http://blag.esotericsystems.at/igor/does/face-palm
I'm sorry :C I replied (to all) on my phone, not noticing it included
the ML :C
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
Re: Moving the Documentation
Posted by Igor Galić <i....@brainsware.org>.
Alan, there is a bridge for Doxygen access already, we'd just have to find out how to integrate it into the build, which I didn't have time for yet.
https://github.com/michaeljones/breathe
"Alan M. Carroll" <am...@network-geographics.com> wrote:
>Igor;
>
>You can take a look here[1] at some stuff I'm working on for a client.
>This is very private until I get around to being able to generate the
>public and private parts independently. Hopefully the main part (about
>the cache) can be integrated back to the main document area. If I get
>some time over the summer I will try to look at extending it to be able
>to access Doxygen output.
>
>[1] http://people.apache.org/~amc/ats/cache/
--
Sent from my phone. Please excuse my brevity.