aurora-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bill Farner <wfar...@apache.org>
Subject Re: Docs
Date Tue, 08 Apr 2014 18:22:26 GMT
I'd like to revisit this, since we gain a lot by exposing our docs in more
places (http://docs.cloudstack.apache.org/ is wonderful, we should
replicate that).  If this can indeed be automated, it seems like a huge
win.  I had not heard of pandoc before, it looks awesome!

*Sebastien* - a few questions for you, so we can learn from cloudstack:

- What is the motivation behind cloudstack's docs being in a separate
repository?

- I noticed the cloudstack repo uses .md and cloudstack-docs uses .rst, any
specific reasons for the difference?

- Is the .md -> .rst a requirement, or just preferable?  I'm not married to
.md, just curious what's at play.



-=Bill


On Tue, Feb 18, 2014 at 1:05 PM, Sebastien Goasguen <runseb@gmail.com>wrote:

>
> On Feb 18, 2014, at 9:42 AM, Jake Farrell <jfarrell@apache.org> wrote:
>
> > Based on what i've seen in other projects around the ASF I would say that
> > we should keep the docs on the core website and not external. This will
> > help the main websites seo and docs that are pushed externally tend to
> not
> > get updated as much as they are forgotten about.
> >
>
> My experience has been as committer on cloudstack and libcloud. IMHO the
> ASF content management system is a bit of a pain and still svn based.
> So while I tend to agree that the docs should be local to the site itself,
> readthedocs.org (RTD) provides some very interesting features, like
> github integration.
> This helps in getting new folks to contribute documentation because a pull
> request is just a click away.
>
> To your concerns, RTD does provide canonical URLs that help with SEO.
> Finally, the docs remain part of the same code repo and the doc site gets
> updated automatically on each commit. So there is nothing getting out of
> date. You edit the .rst files, and it gets published as soon as the github
> mirror sees the new commit.
>
> I personally think it's cool and looks good, but that's you guys's call.
>
> -sebastien
>
> > -Jake
> >
> >
> > On Mon, Feb 17, 2014 at 3:04 PM, Dave Lester <dave@ischool.berkeley.edu
> >wrote:
> >
> >> Sebastien,
> >>
> >> This is great, thank you!
> >>
> >> There were a few bugs in our existing tooling for rendering docs on the
> >> site which has prevented rendering the docs as-is (delayed on part;
> >> although JakeF offered to help). I am inclined to switch entirely to
> what
> >> you've contributed here seeing -- what do others think?
> >>
> >> A few questions this
> >>
> >> * Are folks ok with a switch from markdown to rst?
> >> * Can this handle translated docs as well? Long-term we may want that.
> >> * Can we automate the generation of these docs? The solution we were
> close
> >> to going live with was a simple rake command.
> >>
> >> Thanks again,
> >>
> >> Dave
> >>
> >> On Monday, February 17, 2014, sebgoa <runseb@gmail.com> wrote:
> >>
> >>> Hi,
> >>>
> >>> Since I was testing aurora today I noticed there was no documentation
> >> site
> >>> that I could see, other than the markdown files in the repo.
> >>>
> >>> So I went ahead and did a little prototype for you:
> >>>
> >>> http://apache-aurora-incubating.readthedocs.org/en/latest/index.html
> >>>
> >>> I am using this for CloudStack and it's also used for Apache libcloud.
> >>> It uses sphinx to organize docs, it's based on restructured text which
> is
> >>> fairly close to markdown.
> >>> It can be built on the fly thanks to a service hook on the github
> mirror
> >>> It's hosted by readthedocs.
> >>> It generates epub, pdf and can manage releases.
> >>>
> >>> You can see how I reorganize the tree at:
> >>>
> >>> https://github.com/runseb/incubator-aurora/tree/master/docs
> >>>
> >>> I took the existing markdown files and converted everything to .rst
> using
> >>> pandoc. There are a few gotchas here and there that need to be fixed.
> >>>
> >>> Let me know if that's something that would be of interest, I would be
> >>> happy to clean it up and organize the content to have a proper TOC and
> >> then
> >>> submit a patch.
> >>>
> >>> Cheers,
> >>>
> >>> -Sebastien
> >>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message