activemq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Clebert Suconic <clebert.suco...@gmail.com>
Subject Re: How to rebuild the docs for Artemis?
Date Fri, 11 Nov 2016 23:24:59 GMT
if you build :


man -Prelease install


it will be somewhere on the distribution.



the other way is if you install gitbook (best it google installing
gitbook now, I'm on PTO today, I can find you a better hint tomorrow
or so.. I'm out of my computer today).


if you go under ./docs/en... something like that, after installing
gitbook you can do:


$ gitbook build


you an also do gitbook build pdf
gitbook build mobi
gitbook bulild epub


but that needs another tool used by gitbook.





I can find you better links tomorrow on how to install gitbook (better
yet I can check the hacking guide if they don't include it already).

On Fri, Nov 11, 2016 at 5:54 PM, John D. Ament <johndament@apache.org> wrote:
> On Fri, Nov 11, 2016 at 2:57 PM Justin Bertram <jbertram@apache.com> wrote:
>
>> > Most projects treat their documentation as continuous.  Committers can
>> push in changes whenever relevant.
>>
>> Certainly a case can be made for wiki-style documentation that is outside
>> the code-base and can be visibly updated at any point.  I've worked with
>> documentation like that, and while it was convenient for some things it
>> usually became cumbersome as the software matured and features were added,
>> deprecated, etc.  Extra bits of documentation needed to be added to
>> articles indicating which versions supported what functionality, etc.
>>
>> I much prefer keeping the documentation as part of the code-base so it is
>> versioned and tracked appropriately along with the software.  Each release
>> has its own version of the documentation so it is clear what version it
>> applies to.  JIRAs can be opened for documentation fixes, etc.  Aside from
>> ad hoc updates to fix small errors I'm not currently aware of any use-cases
>> where the wiki-style approach is superior.
>>
>
> I'm against the idea of storing the docs outside the source repository.  It
> just makes sense for them to live together.  When you're looking at a
> release bundle, the docs within it should match the release you pulled down.
>
> I don't have an issue with us hosting multiple releases worth of docs, even
> though at apache we only ever consider the latest release as valid.  I
> think it would be beneficial for us to have docs setup for the current
> snapshot as well.  This way we can see if users have feedback on the
> current goings on.  That's where I'm talking about the continuous aspect of
> this.  They could even go into a SNAPSHOT folder.
>
> BTW, neither of these emails tell me how to build the docs ;-)  Any hints?
>
>
>>
>>
>> Justin
>>
>> ----- Original Message -----
>> From: "John D. Ament" <johndament@apache.org>
>> To: dev@activemq.apache.org
>> Sent: Friday, November 11, 2016 10:44:12 AM
>> Subject: How to rebuild the docs for Artemis?
>>
>> All,
>>
>> I just filed https://issues.apache.org/jira/browse/ARTEMIS-849 as I saw
>> the
>> CDI integration docs were missing (was discussing with someone who was
>> interested, and the link didn't work for me).  I suspect that the reason
>> they're not working is because its not on the SUMMARY file.
>>
>> What I don't see is how to actually rebuild the docs locally.  There's no
>> pom file in docs.  Is there something else that generate the documentation
>> folder?  In fact the hacking guide indicates its via maven -
>>
>> https://github.com/apache/activemq-artemis/blob/master/docs/hacking-guide/en/building.md
>>  .
>>
>> The other thing that I'm not sure about is if the docs can only be updated
>> within the release, or if we can patch them after the release has gone
>> out?  I don't think this warrants a 1.5.1, but at the same time would like
>> to see it fixed before another release goes out.
>>
>> Most projects treat their documentation as continuous.  Committers can push
>> in changes whenever relevant.
>>
>> John
>>



-- 
Clebert Suconic

Mime
View raw message