lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Troy Howard <thowar...@gmail.com>
Subject Re: [Lucene.Net] Blog Setup
Date Wed, 15 Feb 2012 20:29:21 GMT
Speaking of github... we've got a 6 month old pull request hanging out
there that really should be paid attention to. Just so folks know that
we care about encouraging contributions.

-T


On Wed, Feb 15, 2012 at 12:25 PM, Troy Howard <thoward37@gmail.com> wrote:
> My thought was just "we should host our documentation externally" and
> RTD that was the first thing that came to mind.. You're right that
> tool chain is kind of unfortunate.
>
> Another option would be to use GitHub pages and just build our HTMl on
> the build server then push to GitHub to update it. Then we don't have
> to use any weird intermediate steps and can just take whatever HTML
> output we like and use that. In order to function atomically, we'd
> have to add these steps:
>
> ... build docs to HTML with Sandcastle ...
> - git clone git@github.com:apache/lucenenet.github.com
> - git add .
> - git commit -m "time to make the docs"
> - git push (configure the project with a deploy key for the account
> our CI server is using)
>
> Then our doc site (which would be http://lucenenet.github.com) would
> be auto-magically updated.
>
> That might be the lowest impact way of hosting docs externallly.
>
> On Wed, Feb 15, 2012 at 11:54 AM, Christopher Currens
> <currens.chris@gmail.com> wrote:
>> I guess it wouldn't be terribly difficult to do, we would have to convert
>> all of the shfbproj to whatever doxygen uses.  I do think it's a little
>> weird to use the python-style of documentation in a .NET project however.
>>  I personally have never been a fan of python documentation in general
>> simply because I'm used the the MSDN style docs, where I have a nice TOC on
>> the left that I can directly browse to anything fairly easily (think the
>> documentation to MongoDb  http://api.mongodb.org/csharp/1.3.1/ ).  While
>> you do get a TOC on documentation for sphinx style, it limits you to the
>> current topic (and it's all on a single page using named anchors), so I
>> personally find it cluttered.
>>
>> However, that may not matter, since developers would have access to the CHM
>> (though I'd prefer sandcastle's output over doxygen's), so they wouldn't
>> have to use the online docs if they didn't want to.  Plus, I may be in the
>> minority here with my opinion of what the docs should look like.  Idk, just
>> makes sense to me to use .NET tools for the project.  Of course, I'd take
>> Sphinx over javadoc any day...It hurts my eyes! :P
>>
>>
>> Thanks,
>> Christopher
>>
>> On Wed, Feb 15, 2012 at 11:36 AM, Troy Howard <thoward37@gmail.com> wrote:
>>
>>> My understanding is that ASF cares about what is hosted at ASF more
>>> than they care about what isn't hosted at ASF... So you're free to do
>>> whatever you like externally, hence the GitHub mirrors and NuGet and
>>> what not.
>>>
>>> Regarding readthedocs -- it uses Sphinx/ReStructured Text...So we'd
>>> have to convert the XML to that format. There's a project for that
>>> called breathe (http://michaeljones.github.com/breathe/index.html). So
>>> the build server could add steps that would:
>>>
>>> - build to binary
>>> - run doxygen to create xml
>>> - run breathe to convert to RST
>>>
>>> It could commit that to some other repo like say, on github.. (since
>>> pulling from a repo is how RTD ingests content).. then on the RTD
>>> servers it'll pull the repo, look for a conf.py file (very simple
>>> python file) and then run sphinx-build against that directory,
>>> creating documentation for us.
>>>
>>> Woot! At least that way it wouldn't bomb ASF's infrastructure.
>>>
>>> I agree with Prescott that long term, using SVN for this is just not
>>> gonna work out. Docs do change quickly.
>>>
>>> -T
>>>
>>>
>>> On Wed, Feb 15, 2012 at 11:18 AM, Christopher Currens
>>> <currens.chris@gmail.com> wrote:
>>> > That's similar to a suggestion Stefan made in another email:
>>> >
>>> >>  The only alternative would be [...] running a
>>> >> dynamic server on a dedicated VM.  The later would
>>> >> be easier to negotiate for a top level project.
>>> >
>>> > Though, his response seems to imply that it would need to stay hosted on
>>> > Apache servers?  I'm really only saying that because it was suggested to
>>> > negotiate it for a top level project, and the use of an outside server
>>> > wasn't actually suggested by him.  If we can host outside of Apache
>>> > servers, that does seems like the most straightforward answer to our
>>> > problem, that would require the least amount of changes to our build
>>> > process (probably).
>>> >
>>> > In regards to readthedocs.org, I think it only supports restructured
>>> text?
>>> >  You have to use Sphinx (python) to output your documentation which uses
>>> > restructured text.  I don't know if we can output that from sandcastle.
>>> >  Maybe there would be another way to export the xmldoc to that format,
>>> but
>>> > idk, probably not worth the amount of effort it would take to put that in
>>> > our build steps.
>>> >
>>> >
>>> > Thanks,
>>> > Christopher
>>> >
>>> > On Wed, Feb 15, 2012 at 10:59 AM, Troy Howard <thoward37@gmail.com>
>>> wrote:
>>> >
>>> >> Why not move docs to http://readthedocs.org/
>>> >>
>>> >> On Wed, Feb 15, 2012 at 10:45 AM, Christopher Currens
>>> >> <currens.chris@gmail.com> wrote:
>>> >> > Erg.  Was it related to the whole documentation thing?  I'm pretty
>>> sure
>>> >> > it's "frowned upon" for our documentation to break SVN every time
we
>>> do a
>>> >> > release, so we should probably figure out a solution for that.
 :P
>>> >> >
>>> >> >
>>> >> > Thanks,
>>> >> > Christopher
>>> >> >
>>> >> > On Wed, Feb 15, 2012 at 10:28 AM, Prescott Nasser <
>>> geobmx540@hotmail.com
>>> >> >wrote:
>>> >> >
>>> >> >>
>>> >> >> Ick, I'm in the middle of publishing and working with Joe @
site-dev.
>>> >> >> We've totally f'd up svn. He's asked we stop doing things and
he's
>>> >> going to
>>> >> >> fix it and get back to us... At least we're active.. ;) ~P
>>> >> >>  > Date: Wed, 15 Feb 2012 10:20:29 -0800
>>> >> >> > From: currens.chris@gmail.com
>>> >> >> > To: lucene-net-dev@lucene.apache.org
>>> >> >> > Subject: Re: [Lucene.Net] Blog Setup
>>> >> >> >
>>> >> >> > I made some changes to the website in staging.  Just
a few things
>>> >> >> regarding
>>> >> >> > the blog list, a little bit of left padding and adding
a recent
>>> news
>>> >> >> header
>>> >> >> > above it.  I also changed the link style a little bit.
 Feel free
>>> to
>>> >> >> revert
>>> >> >> > any/all changes I've made. :)
>>> >> >> >
>>> >> >> >
>>> >> >> > Thanks,
>>> >> >> > Christopher
>>> >> >> >
>>> >> >> > On Tue, Feb 14, 2012 at 9:05 PM, Prescott Nasser <
>>> >> geobmx540@hotmail.com
>>> >> >> >wrote:
>>> >> >> >
>>> >> >> > >
>>> >> >> > > Editing the site: http://www.apache.org/dev/cms#usage
Staging:
>>> >> >> > > http://lucene.net.staging.apache.org/lucene.net/
>>> >> >> > >  > Date: Tue, 14 Feb 2012 11:03:58 -0800
>>> >> >> > > > From: currens.chris@gmail.com
>>> >> >> > > > To: lucene-net-dev@lucene.apache.org
>>> >> >> > > > Subject: Re: [Lucene.Net] Blog Setup
>>> >> >> > > >
>>> >> >> > > > Looks like the blog was successfully setup (that
was quick!).
>>>  You
>>> >> >> can
>>> >> >> > > > access it here:  https://blogs.apache.org/lucenenet/
>>> >> >> > > >
>>> >> >> > > > I've migrated the whopping 3 new entries we
already have on our
>>> >> >> > > > index/front-page in the news section over to
the blog.  I would
>>> >> give
>>> >> >> a
>>> >> >> > > shot
>>> >> >> > > > at integrating it into the website, but I actually
have no idea
>>> >> how
>>> >> >> to
>>> >> >> > > edit
>>> >> >> > > > the website. :)
>>> >> >> > > >
>>> >> >> > > >
>>> >> >> > > > Thanks,
>>> >> >> > > > Christopher
>>> >> >> > > >
>>> >> >> > > > On Mon, Feb 13, 2012 at 6:17 PM, Prescott Nasser
<
>>> >> >> geobmx540@hotmail.com
>>> >> >> > > >wrote:
>>> >> >> > > >
>>> >> >> > > > >
>>> >> >> > > > > I've submitted a ticket here:
>>> >> >> > > > > https://issues.apache.org/jira/browse/INFRA-4433
I only
>>> added
>>> >> my
>>> >> >> > > name, I
>>> >> >> > > > > wasn't sure who else would want access
- if you do want it,
>>> >> submit
>>> >> >> a
>>> >> >> > > > > comment to that ticket with your apache
username and full
>>> name.
>>> >> >> I'm
>>> >> >> > > going
>>> >> >> > > > > to try and integrate this into the site
soon. I also have
>>> some
>>> >> >> ideas
>>> >> >> > > about
>>> >> >> > > > > how to utilize the blog that I'll outline
after I get it up
>>> and
>>> >> >> > > running ~P
>>> >> >> > > > >  > From: bodewig@apache.org
>>> >> >> > > > > > To: lucene-net-dev@incubator.apache.org
>>> >> >> > > > > > Date: Mon, 13 Feb 2012 13:39:11 +0100
>>> >> >> > > > > > Subject: [Lucene.Net] Blog Setup
>>> >> >> > > > > >
>>> >> >> > > > > > Hi all,
>>> >> >> > > > > >
>>> >> >> > > > > > If we want a blog for Lucene.Net on
blogs.apache.org, the
>>> >> >> > > instructions
>>> >> >> > > > > > to request one are at
>>> >> >> > > > > > <
>>> >> >> > >
>>> >> >>
>>> https://cwiki.apache.org/confluence/display/INFRA/Resource+request+FAQs
>>> >> >> > > > > >
>>> >> >> > > > > > Mainly we should have a list of ASF
ids of the initial set
>>> of
>>> >> >> admins
>>> >> >> > > and
>>> >> >> > > > > > authors.
>>> >> >> > > > > >
>>> >> >> > > > > > I had a look at how the RSS snippets
are added to
>>> >> www.apache.org
>>> >> >> 's
>>> >> >> > > index
>>> >> >> > > > > > page and it doesn't look to difficult
to adapt.
>>> >> >> > > > > >
>>> >> >> > > > > > In
>>> >> >> > > > > > <
>>> >> >> > > > >
>>> >> >> > >
>>> >> >>
>>> >>
>>> https://svn.apache.org/repos/asf/infrastructure/site/trunk/content/index.html
>>> >> >> > > > > >
>>> >> >> > > > > > there is
>>> >> >> > > > > >
>>> >> >> > > > > > {% for e in blog.list %}
>>> >> >> > > > > > <h4><a href="{{ e.url }}">{{
e.title }}</a></h4>
>>> >> >> > > > > > <div class="section-content">{{
>>> >> >> e.content|safe|truncatewords_html:50
>>> >> >> > > > > }}</div>
>>> >> >> > > > > > <hr>
>>> >> >> > > > > > {% endfor %}
>>> >> >> > > > > >
>>> >> >> > > > > > which iterates over a blogs collection
created in path.pmvia
>>> >> >> > > > > >
>>> >> >> > > > > > [qr!^/index\.html$!, news_page =>
>>> >> >> > > > > >       {
>>> >> >> > > > > >         blog     => ASF::Value::Blogs->new(blog
=>
>>> >> "foundation",
>>> >> >> > > limit=>
>>> >> >> > > > > 3),
>>> >> >> > > > > >       },
>>> >> >> > > > > >     ],
>>> >> >> > > > > >
>>> >> >> > > > > > and uses the ASF::Value::Blog package
that is part of the
>>> CMS.
>>> >> >> > > > > > <
>>> >> >> > > > >
>>> >> >> > >
>>> >> >>
>>> >>
>>> https://svn.apache.org/repos/infra/websites/cms/build/lib/ASF/Value/Blogs.pm
>>> >> >> > > > > >
>>> >> >> > > > > >
>>> >> >> > > > > > So getting content from the blog to
the main page is pretty
>>> >> >> easy.  I
>>> >> >> > > > > > think the main site is re-created
every fifteen minutes to
>>> >> ensure
>>> >> >> > > things
>>> >> >> > > > > > are fresh, not sure how one would
go about this for a page
>>> >> that
>>> >> >> > > doesn't
>>> >> >> > > > > > change that often (manually triggering
buildbot might be an
>>> >> >> option).
>>> >> >> > > > > > We'd need to ask this on the site-dev
mailing list which is
>>> >> >> > > dedicated to
>>> >> >> > > > > > the CMS.
>>> >> >> > > > > >
>>> >> >> > > > > > Stefan
>>> >> >> > > > >
>>> >> >> > > > >
>>> >> >> > >
>>> >> >> > >
>>> >> >>
>>> >> >>
>>> >>
>>>

Mime
View raw message