deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pete Muir <pm...@redhat.com>
Subject Re: [suggestion] - Documentation
Date Wed, 25 Jul 2012 15:22:06 GMT

On 25 Jul 2012, at 16:16, Matt Benson wrote:

> On Wed, Jul 25, 2012 at 8:58 AM, Pete Muir <pmuir@redhat.com> wrote:
>> 
>> On 25 Jul 2012, at 07:17, Mark Struberg wrote:
>> 
>>> David, the CMS is already set up and running (in SVN [1]). We just need a bit
more stylish css.
>>> 
>>> And you can perfectly create pdf docs out of markdown.
>>> 
>>> Of course we can also use alternative formats. But to me this is like a colour
preference - markdown is supported out of the box and provides all needed options.
>> 
>> My only concern here is that Markdown doesn't support a few useful things for full
on docs (vs readmes and snippets of text):
> 
> FWIW,
>> 
>> * admonitions
> I.e., warnings?  What are you looking for here?

Yes, admonitions is the term given (I think by docbook) to the boxouts that are e.g. Warning,
Info, Important.

> 
>> * callouts on code
> Again, not sure I know what you're meaning here.

I can have a little icon (e.g. a 1), next to a line of code, then a table at the bottom of
the codeblock that links to that. Allows you to annotate a code block with notes.

> 
>> * a standard way of indicating what the source language of a code block is
> Apache CMS has this.

Cool. How would this work if we were also producing pdfs and epubs? Is this a standard extension
to markdown?

> 
>> * definition lists
> Example?

http://www.w3schools.com/tags/tag_dl.asp

> 
>> * tables (though there are extensions to Markdown that support this, idk if Apache
CMS' implementation of Markdown does?)
> Apache CMS has this extension enabled.
> 
> Matt
> 
>> 
>> I find all of these things useful when writing docs.
>> 
>> It was for these reasons that we decided at JBoss we needed more than MarkDown for
docs. We choose AsciiDoc as our extended format for docs:
>> 
>> * It can process 95% of markdown's syntax
>> * It supports all of the above deficiencies in markdown
>> * It has a good toolchain built in, that spits out pdf and epub
>> * It can convert to docbook
>> * It has good docs
>> 
>> I'm not suggesting that DeltaSpike should do the same, just contributing our findings
:-)
>> 
>>> 
>>> Shane, I don't think I bypassed anyone. We discussed this since 6 months and
noone started working on it. Thus I finally dropped a mail and then implemented it. I also
got no stop mail back then.
>>> Honestly I really don't care which format we use, IF someone else is doing the
work and others can easily add documentation.
>>> 
>>> 
>>> LieGrue,
>>> strub
>>> 
>>> 
>>> 
>>> [1] http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/
>>> 
>>> 
>>> 
>>> ----- Original Message -----
>>>> From: David Blevins <david.blevins@gmail.com>
>>>> To: deltaspike-dev@incubator.apache.org
>>>> Cc: Mark Struberg <struberg@yahoo.de>
>>>> Sent: Wednesday, July 25, 2012 2:37 AM
>>>> Subject: Re: [suggestion] - Documentation
>>>> 
>>>> T he answer to both these questions really that the CMS creates
>>>> "websites", some details on that below
>>>> 
>>>> I'll note that the CMS is svn based -- maybe undesirable given the use of
>>>> git.
>>>> 
>>>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote:
>>>> 
>>>>> Does the choice of Apache CMS for hosting documentation meet the following
>>>> requirements?
>>>>> 
>>>>> 1) Making available the documentation for previously released versions
of
>>>> DeltaSpike.
>>>> 
>>>> If by "make available" the intention is browsable on the website, then
>>>> sure there are ways to handle that.
>>>> 
>>>>> 2) Making available the documentation in offline formats, such as HTML
or
>>>> PDF available for download.
>>>> 
>>>> Certainly you can use the same source to generate non-website looking HTML.
>>>> Same goes for PDF.
>>>> 
>>>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent
>>>> it.  It'd be something we setup ourselves and could be done via a CI server
>>>> or something done at release time.
>>>> 
>>>> Basically the CMS is a system that is for generate website html using the
>>>> following layout:
>>>> 
>>>> - content/<source-files-and-directories>
>>>> - lib/<site-generating-perl-functions>
>>>> - templates/<whatever-you-need-for-templates>
>>>> 
>>>> When something in 'content/' is updated, it will run it through lib/
>>>> (which leverages templates/) and save the resulting html to disk and take
care
>>>> of synching that html file from staging to production.
>>>> 
>>>> When something in 'lib/' or 'templates/' is updated, it pretends
>>>> as if everything in 'content/' has changed and performs the above step
>>>> on every source file.
>>>> 
>>>> You can organize the 'content/' dir however you want.  That could mean:
>>>> 
>>>> - content/v0.1/
>>>> - content/v0.2/
>>>> - content/current/
>>>> 
>>>> Where 'current' gets versioned on release.  Or anything at all.  Maybe
>>>> just:
>>>> 
>>>> - content/<wild-wild-west>
>>>> 
>>>> 
>>>> So the short answer is there isn't anything there to prevent or help the
two
>>>> points.
>>>> 
>>>> In terms of generating outside the CMS which is what would be needed for
say,
>>>> turning many files into one file such as a zip of html or a PDF, it's up
to
>>>> us.  There are projects that do it via buildbot.  Buildbot is not so much
a CI
>>>> tool as it is "cron with a webUI" and also happens to have the ability
>>>> to be trigger by commits.
>>>> 
>>>> Really, you can get anything done with buildbot without much in the way of
>>>> restrictions.  It's a mediocre CI system and an amazing cron replacement.
>>>> 
>>>> 
>>>> -David
>>>> 
>> 


Mime
View raw message