[prev in list] [next in list] [prev in thread] [next in thread]
List: markus-dev
Subject: Re: Markus website & documentation
From: Nelle Varoquaux <nelle.varoquaux () gmail ! com>
Date: 2012-02-26 22:15:44
Message-ID: CAE-UAvSTz99m=JswPJ6uK+V4femy7yfiDHrbpKu38v-=_=pFbg () mail ! gmail ! com
[Download RAW message or body]
Hi Severin,
1. This would replace the current website available on
> markusproject.org, right? It would also be user guide, website,
> contributer guide, etc. all in one?
>
Yes, that is correct.
> 2. If we go with this, that would mean we'd have another Git repo (for
> which we can have looser permission restrictions), correct?
>
There are several options for that. We could include the documentation
directly with the source code (in the very empty doc folder), or create a
repository for it (or replace one of the repository we already have, such
as the wiki one, or the website one). We just need to keep in mind that if
it is rebuild after each commit, we might want to check what goes in (or at
least have some mail send if the build fails).
> 3. How does multiple version support work? Can parts of the
> documentation be versioned an other parts not? Say section A applies
> to MarkUs version 0.5, 0.6 and 0.9, but not 0.8 would we need to tag
> every paragraph with the list of applicable versions?
>
It would be tagged as a whole, with a git tag. For the build, there are two
options possible:
- have different urls for different version,
markusproject.orgredirecting to the "stable" one.This is how
scikits-learn works (
http://scikit-learn.org/ for the stable version,
http://scikit-learn.org/dev/ for the development one, and
http://scikit-learn.org/0.9 for the 0.9 release etc...
- have the build of the website itself always be the stable version, and
in the documentation part, displaying links to different version of
the documentation. This is how scikits-image works:
http://scikits-image.org/docs/
Both solution have drawbacks.
I don't know how to configure sphinx for those two options, but I'm pretty
sure it is straight forward (fingers crossed).
Thanks,
N
>
> I'm very much in favour of doing this. Thanks for your hard work on this!
>
> Cheers,
> Severin
>
> On Sun, Feb 26, 2012 at 4:44 PM, Nelle Varoquaux
> <nelle.varoquaux@gmail.com> wrote:
> > Hi Team,
> >
> > I've been working on solutions to improve both the website and the
> > documentation we have. I've made a draft project with sphinx, a tool
> often
> > used in the python community to both build websites and documentation. It
> > uses restructured text (as our wiki). Benjamin built it on
> > markusproject: http://www.markusproject.org/dev/doc/index.html
> > And the source code can be found here:
> https://github.com/NelleV/MarkusDoc
> >
> > This is what it could look like. There's still a lot of work to make it
> > usable, but that would allow use to make the web site a bit nicer, but
> also
> > to migrate all our documentation (and clean it up), and have it
> accessible
> > directly on the website. As it is already in restructured texts, we would
> > mostly need to reorganise it, and delete all the duplicate pages.
> > The design can also be tweaked in order to look more like the
> application.
> >
> > The documentation can then be tagged with version (ie, it would be
> released
> > with the code). It can be easily build nightly, or with every commit, to
> > have a development version online on the website.
> > Also, right now, we have a problem with the wiki being in two different
> > places: one where developers who don't have read and write access can
> create
> > pull request, and another one which is build, and where core devs can
> edit.
> > These are often out of sync. That would allow us to use the wiki only for
> > purposes such as articles, conferences, code sprint organisation, and
> leave
> > the documentation aside, by itself, in a repository people can commit to
> (or
> > submit PR).
> >
> > What do you think ?
> >
> > Cheers,
> > N
>
[Attachment #3 (text/html)]
Hi Severin,<br><br><div class="gmail_quote"><blockquote class="gmail_quote" \
style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> 1. This would \
replace the current website available on<br> <a href="http://markusproject.org" \
target="_blank">markusproject.org</a>, right? It would also be user guide, \
website,<br> contributer guide, etc. all in \
one?<br></blockquote><div><br></div><div>Yes, that is correct.</div><div> \
</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc \
solid;padding-left:1ex"> 2. If we go with this, that would mean we'd have another \
Git repo (for<br> which we can have looser permission restrictions), \
correct?<br></blockquote><div><br></div><div>There are several options for that. We \
could include the documentation directly with the source code (in the very empty doc \
folder), or create a repository for it (or replace one of the repository we already \
have, such as the wiki one, or the website one). We just need to keep in mind that if \
it is rebuild after each commit, we might want to check what goes in (or at least \
have some mail send if the build fails).</div> <div> </div><blockquote \
class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc \
solid;padding-left:1ex"> 3. How does multiple version support work? Can parts of \
the<br> documentation be versioned an other parts not? Say section A applies<br>
to MarkUs version 0.5, 0.6 and 0.9, but not 0.8 would we need to tag<br>
every paragraph with the list of applicable \
versions?<br></blockquote><div><br></div><div>It would be tagged as a whole, with a \
git tag. For the build, there are two options possible:</div><div><br></div><div> - \
have different urls for different version, <a \
href="http://markusproject.org">markusproject.org</a> redirecting to the \
"stable" one.This is how scikits-learn works (<a \
href="http://scikit-learn.org/">http://scikit-learn.org/</a> for the stable version, \
<a href="http://scikit-learn.org/dev/">http://scikit-learn.org/dev/</a> for the \
development one, and <a \
href="http://scikit-learn.org/0.9">http://scikit-learn.org/0.9</a> for the 0.9 \
release etc...</div> <div> - have the build of the website itself always be the \
stable version, and in the documentation part, displaying links to different version \
of the documentation. This is how scikits-image works: <a \
href="http://scikits-image.org/docs/">http://scikits-image.org/docs/</a></div> \
<div><br></div><div>Both solution have drawbacks.</div><div>I don't know how to \
configure sphinx for those two options, but I'm pretty sure it is straight \
forward (fingers crossed).</div><div><br></div><div>Thanks,</div> <div>N</div><div> \
</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc \
solid;padding-left:1ex"> <br>
I'm very much in favour of doing this. Thanks for your hard work on this!<br>
<br>
Cheers,<br>
Severin<br>
<div class="HOEnZb"><div class="h5"><br>
On Sun, Feb 26, 2012 at 4:44 PM, Nelle Varoquaux<br>
<<a href="mailto:nelle.varoquaux@gmail.com">nelle.varoquaux@gmail.com</a>> \
wrote:<br> > Hi Team,<br>
><br>
> I've been working on solutions to improve both the website and the<br>
> documentation we have. I've made a draft project with sphinx, a tool \
often<br> > used in the python community to both build websites and documentation. \
It<br> > uses restructured text (as our wiki). Benjamin built it on<br>
> markusproject: <a href="http://www.markusproject.org/dev/doc/index.html" \
target="_blank">http://www.markusproject.org/dev/doc/index.html</a><br> > And the \
source code can be found here: <a href="https://github.com/NelleV/MarkusDoc" \
target="_blank">https://github.com/NelleV/MarkusDoc</a><br> ><br>
> This is what it could look like. There's still a lot of work to make it<br>
> usable, but that would allow use to make the web site a bit nicer, but also<br>
> to migrate all our documentation (and clean it up), and have it accessible<br>
> directly on the website. As it is already in restructured texts, we would<br>
> mostly need to reorganise it, and delete all the duplicate pages.<br>
> The design can also be tweaked in order to look more like the application.<br>
><br>
> The documentation can then be tagged with version (ie, it would be released<br>
> with the code). It can be easily build nightly, or with every commit, to<br>
> have a development version online on the website.<br>
> Also, right now, we have a problem with the wiki being in two different<br>
> places: one where developers who don't have read and write access can \
create<br> > pull request, and another one which is build, and where core devs can \
edit.<br> > These are often out of sync. That would allow us to use the wiki only \
for<br> > purposes such as articles, conferences, code sprint organisation, and \
leave<br> > the documentation aside, by itself, in a repository people can commit \
to (or<br> > submit PR).<br>
><br>
> What do you think ?<br>
><br>
> Cheers,<br>
> N<br>
</div></div></blockquote></div><br>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic