deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Benson <gudnabr...@gmail.com>
Subject Re: [suggestion] - Documentation
Date Wed, 25 Jul 2012 15:36:55 GMT
On Wed, Jul 25, 2012 at 10:22 AM, Pete Muir <pmuir@redhat.com> wrote:
>
> 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?

Yes; the code highlighting is done with
http://freewisdom.org/projects/python-markdown/CodeHilite; depending
on the structure of whatever mechanism would be theoretically used to
produce other formats, we'd presumably just make the same extensions
available.

>
>>
>>> * definition lists
>> Example?
>
> http://www.w3schools.com/tags/tag_dl.asp

As it turns out,
http://freewisdom.org/projects/python-markdown/Definition_Lists is
also enabled in the Apache CMS.  The full list of enabled extensions
is at http://www.apache.org/dev/cmsref#markdown .

Matt

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