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 <thowar...@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 g...@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.ch...@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 <thowar...@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.ch...@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 <thowar...@gmail.com> >>> wrote: >>> > >>> >> Why not move docs to http://readthedocs.org/ >>> >> >>> >> On Wed, Feb 15, 2012 at 10:45 AM, Christopher Currens >>> >> <currens.ch...@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 < >>> geobmx...@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.ch...@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 < >>> >> geobmx...@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.ch...@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 < >>> >> >> geobmx...@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: bode...@apache.org >>> >> >> > > > > > To: lucene-net-...@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 >>> >> >> > > > > >>> >> >> > > > > >>> >> >> > > >>> >> >> > > >>> >> >> >>> >> >> >>> >> >>>
