Building help.ubuntu.com

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Building help.ubuntu.com

Shaun McCance-2
Hi all,

Currently, if I recall things correctly, help.ubuntu.com is built with
a set of scripts that call yelp-build with the -x option for custom
styling. Rather than have every project roll its own orchestration
scripts, I've been working on a tool called Pintail to manage entire
documentation sites:

https://github.com/projectmallard/pintail

It's built on the same transformations as what you're using now, which
are the same transformations used internally in Yelp. Your custom
styling will transfer to Pintail with little or no modification.

Some of the advantages of switching:

1) It just does all the work of building the site in a single command.
You can trigger this on a webhook for continuous deployment, or you can
publish manually on releases.

2) It understands translations and builds them for you.

3) It knows how to find documents in different git repositories. You
don't have to put all your documents in one repository. Right now, it
only speaks git, but I could teach it about bzr with minimal effort.

4) It can have integrated search built on Elasticsearch. The search is
fully aware of translations, and can keep searches restricted within
documents. So, for example, when you search in the server guide, you
won't get hits from the user guide. You can keep using the Google site
search you're using now instead, but I'd encourage you to at least look
into the integrated search.

5) It's format-agnostic, with different formats and sources handled by
plugins. Right now, it can handle Mallard, Ducktype, DocBook, and
AsciiDoc.

Pintail is just a new layer on top of the tools you're already using,
so it's not a drastic change for Ubuntu. But it would require some ops
work to set it up. I helped a bit in setting up the current publishing
tool chain. I'd be happy to help with this too.

Anybody want to have a chat to explore feasibility?

--
Shaun



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Building help.ubuntu.com

Doug Smythies
On 2016.09.26 11:27 Shaun McCance wrote:

> Hi all,

Hi Shaun,

>
> Currently, if I recall things correctly, help.ubuntu.com is built with
> a set of scripts that call yelp-build with the -x option for custom
> styling. Rather than have every project roll its own orchestration
> scripts, I've been working on a tool called Pintail to manage entire
> documentation sites:
>
> https://github.com/projectmallard/pintail
>
> It's built on the same transformations as what you're using now, which
> are the same transformations used internally in Yelp. Your custom
> styling will transfer to Pintail with little or no modification.
>
> Some of the advantages of switching:
>
> 1) It just does all the work of building the site in a single command.
> You can trigger this on a webhook for continuous deployment, or you can
> publish manually on releases.
>
> 2) It understands translations and builds them for you.
>
> 3) It knows how to find documents in different git repositories. You
> don't have to put all your documents in one repository. Right now, it
> only speaks git, but I could teach it about bzr with minimal effort.
>
> 4) It can have integrated search built on Elasticsearch. The search is
> fully aware of translations, and can keep searches restricted within
> documents. So, for example, when you search in the server guide, you
> won't get hits from the user guide. You can keep using the Google site
> search you're using now instead, but I'd encourage you to at least look
> into the integrated search.
>
> 5) It's format-agnostic, with different formats and sources handled by
> plugins. Right now, it can handle Mallard, Ducktype, DocBook, and
> AsciiDoc.
>
> Pintail is just a new layer on top of the tools you're already using,
> so it's not a drastic change for Ubuntu. But it would require some ops
> work to set it up. I helped a bit in setting up the current publishing
> tool chain. I'd be happy to help with this too.
>
> Anybody want to have a chat to explore feasibility?

In terms of a time-line, could I suggest that we leave the already in
progress 16.10 alone. Then we could do some trial work or whatever
as part of the 17.04 cycle, starting early in an attempt to avoid
deadline stress.

In the meantime, would it make sense for you to do a build of
help.ubuntu.com so as to understand what we do today? It would be
pretty simple, as we are just replacing the 16.10 desktop help docs
during remaining updates this cycle. All the other stuff stays the same.

Keep in mind that we (the current doc committers) are more custodians
of workflows that were created before our time than we are experts
on the deep details. In particular, I tend to get lost whenever I
have to dig deep into yelp while investigating some issue.

... Doug



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Building help.ubuntu.com

Gunnar Hjalmarsson
On 2016-09-26 22:34, Doug Smythies wrote:
> On 2016.09.26 11:27 Shaun McCance wrote:
>>
>> https://github.com/projectmallard/pintail

Thanks for letting us know, Shaun, and for offering your help. Needless
to say we are interested.

>> Anybody want to have a chat to explore feasibility?

That could be one way, and I would be interested.

> In terms of a time-line, could I suggest that we leave the already
> in progress 16.10 alone. Then we could do some trial work or
> whatever as part of the 17.04 cycle, starting early in an attempt to
> avoid deadline stress.
>
> In the meantime, would it make sense for you to do a build of
> help.ubuntu.com so as to understand what we do today? It would be
> pretty simple, as we are just replacing the 16.10 desktop help docs
> during remaining updates this cycle. All the other stuff stays the
> same.

Yeah, we should probably not change anything before the final release of
the 16.10 desktop docs (which will happen in less than a week).

As regards build of "help.ubuntu.com" it should be mentioned that we
have separate branches for desktop and server, and to get a grasp of
what we do today, it's probably sufficient if Shaun builds one of them.

--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Building help.ubuntu.com

Shaun McCance-2
In reply to this post by Doug Smythies
On Mon, 2016-09-26 at 13:34 -0700, Doug Smythies wrote:

> On 2016.09.26 11:27 Shaun McCance wrote:
>
> >
> > Hi all,
> Hi Shaun,
>
> >
> >
> > Currently, if I recall things correctly, help.ubuntu.com is built
> > with
> > a set of scripts that call yelp-build with the -x option for custom
> > styling. Rather than have every project roll its own orchestration
> > scripts, I've been working on a tool called Pintail to manage
> > entire
> > documentation sites:
> >
> > https://github.com/projectmallard/pintail
> In terms of a time-line, could I suggest that we leave the already in
> progress 16.10 alone. Then we could do some trial work or whatever
> as part of the 17.04 cycle, starting early in an attempt to avoid
> deadline stress.

Absolutely. Changing out tools on 16.10 right would be madness.

> In the meantime, would it make sense for you to do a build of
> help.ubuntu.com so as to understand what we do today? It would be
> pretty simple, as we are just replacing the 16.10 desktop help docs
> during remaining updates this cycle. All the other stuff stays the
> same.

Can somebody remind me where the current build scripts and stuff are?
I'll take a crack at a basic setup in the next couple weeks.

> Keep in mind that we (the current doc committers) are more custodians
> of workflows that were created before our time than we are experts
> on the deep details. In particular, I tend to get lost whenever I
> have to dig deep into yelp while investigating some issue.

Sure. A lot of your tools came from GNOME, and you should always feel
free to reach out to GNOME for help. But your build scripts are kind of
a custom job. Hopefully having those replaced by a maintained upstream
project will make your lives easier. Doc writers shouldn't have to
spend their time doing ops work.

--
Shaun


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Building help.ubuntu.com

Gunnar Hjalmarsson
On 2016-09-27 00:08, Shaun McCance wrote:
> Can somebody remind me where the current build scripts and stuff
> are?

It's in LP Bazaar branches.

Server guide:
https://code.launchpad.net/~ubuntu-core-doc/serverguide/trunk

Desktop guide:
https://code.launchpad.net/~ubuntu-core-doc/ubuntu-docs/trunk

> I'll take a crack at a basic setup in the next couple weeks.
> ...
> A lot of your tools came from GNOME, and you should always feel free
> to reach out to GNOME for help. But your build scripts are kind of a
> custom job. Hopefully having those replaced by a maintained upstream
> project will make your lives easier. Doc writers shouldn't have to
> spend their time doing ops work.

While what you say sounds right, it also brings some anxiety to me. I'm
not quite sure of what "replaced by a maintained upstream project" implies.

Personally I would prefer that we move this forward in small steps.
Maybe, after you have reviewed the branches I linked to, we should
schedule a meeting to talk about it, as you suggested initially.

One thing I'd like to mention is that the focus of the Ubuntu desktop
docs gradually will be moved from Unity 7 to Unity 8 (i.e. Ubuntu Touch
with desktop and phone integrated), and as far as I know it has not yet
been decided which markup language will be used for the latter.

--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Building help.ubuntu.com

Jeremy Bicha-2
In reply to this post by Shaun McCance-2
On Mon, Sep 26, 2016 at 6:08 PM, Shaun McCance <[hidden email]> wrote:
> Can somebody remind me where the current build scripts and stuff are?

https://code.launchpad.net/~ubuntu-core-doc/help.ubuntu.com/help.ubuntu.com

bzr branch lp:help.ubuntu.com

I believe the html files there are manually built from the repos
Gunnar pointed to. A Canonical-managed cron job then publishes from
the help.ubuntu.com repo.

On Mon, Sep 26, 2016 at 8:50 PM, Gunnar Hjalmarsson <[hidden email]> wrote:
> While what you say sounds right, it also brings some anxiety to me. I'm
> not quite sure of what "replaced by a maintained upstream project" implies.

I think there's a bit of miscommunication here. I think Shaun is just
talking about publishing the Help content to the website, not changing
the documentation shipped in the Ubuntu isos.

Jeremy

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Building help.ubuntu.com

Gunnar Hjalmarsson
On 2016-09-27 03:31, Jeremy Bicha wrote:
> On Mon, Sep 26, 2016 at 8:50 PM, Gunnar Hjalmarsson
> <[hidden email]> wrote:
>> While what you say sounds right, it also brings some anxiety to me.
>> I'm not quite sure of what "replaced by a maintained upstream
>> project" implies.
>
> I think there's a bit of miscommunication here. I think Shaun is
> just talking about publishing the Help content to the website, not
> changing the documentation shipped in the Ubuntu isos.

Yeah, I think I got that. And as you said it's currently done in two steps:

1. Build the HTML from respective branch
2. Manually copy the result to the help.ubuntu.com branch from where
   it's automatically copied to the site via a cron script.

Maybe I'm worrying unnecessarily. :) But I still would appreciate a
meeting to clarify a few things before a lot of work is done.

--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Building help.ubuntu.com

Doug Smythies
In reply to this post by Jeremy Bicha-2
On 2016.09.26 19:10 Gunnar Hjalmarsson

> On 2016-09-27 03:31, Jeremy Bicha wrote:
>> On Mon, Sep 26, 2016 at 8:50 PM, Gunnar Hjalmarsson wrote:
>>> While what you say sounds right, it also brings some anxiety to me.
>>> I'm not quite sure of what "replaced by a maintained upstream
>>> project" implies.
>>
>> I think there's a bit of miscommunication here. I think Shaun is
>> just talking about publishing the Help content to the website, not
>> changing the documentation shipped in the Ubuntu isos.
>
> Yeah, I think I got that.

Me too.

> And as you said it's currently done in two steps:
>
> 1. Build the HTML from respective branch
> 2. Manually copy the result to the help.ubuntu.com branch from where
>   it's automatically copied to the site via a cron script.
>
> Maybe I'm worrying unnecessarily. :) But I still would appreciate a
> meeting to clarify a few things before a lot of work is done.

Perhaps we can meet sometime on the docs IRC channel.
I do not hang out there, but can go on as required.

On Mon, Sep 26, 2016 at 15:09 PM, Shaun McCance wrote:
> Doc writers shouldn't have to spend their time doing ops work.

The infrastructure and workflow is actually what I am interested in.
I am not a doc writer.

... Doug
 


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc