New documentation

[Jim Fulton]

I've decided to start working on new buildout docs, starting from scratch. Because:

• doctest-based docs were a horribly failed experiment. (I don't regret trying, but I regret not stopping.)
  
  (But testing docs with manuel is still a good idea.)
  
  The current documentation is truly hideous.
  
  
• A lot has changed with regard to packaging and while we still have a stake, we (I think all) realize that packaging is not our mission, automation is.
  

I've created a new-docs branch and drafted a front page: https://github.com/buildout/buildout/blob/new-docs/doc/index.rst

I lay out sphinx projects a little differently than the default layout.  The master document, aka table of contents is ``contents``.  I use the index page, which is the front page, to try to motivate the reader to care about the project. IMO, the index needs to concisely get the reader to think the project might be something they should use and to get them to read on.  I usually follow up with a getting started section.

The index page lays out some core principles that guide how Buildout works and is used.  At least one of these may be controversial. :) Comments are welcome.

I'm personally not very interested in marketing, but want to make a clear argument and provide decent documentation.  Not that I'm opposed to marketing, but that's not what I'm focussing on.

Having said that, is anyone interested in having a buildout logo?  If so, and if we decide what that should be, I'd be happy to use 99designs to get one designed. (I'm pretty happy with the Newt DB logo I had designed through 99designs.)

I'm about to start working on the getting-started section.

I'm thinking of a script akin to the bootstrap script that builds a virtualenv and uses it to create a buildout.  This has been suggested before, and I've resisted, but I'm coming around.  Does anyone know of such a script that they'd recommend?  If not, I'll start by documenting a fictional script initially. (I love science fiction.)

Jim

--

Jim Fulton
http://jimfulton.info

[Jonathan Ballet]

On February 11, 2017 3:31:02 PM CET, Jim Fulton <j...@jimfulton.info> wrote:

>I'm thinking of a script akin to the bootstrap script that builds a
>virtualenv and uses it to create a buildout. This has been suggested
>before, and I've resisted, but I'm coming around. Does anyone know of
>such
>a script that they'd recommend? If not, I'll start by documenting a
>fictional script initially. (I love science fiction.)

I will ago, I wrote this : https://github.com/multani/buildout-bootstrap-virtualenv

This actually worked quite well until latest setuptools release and I didn't have the chance to put a proper fix but you may be interested nevertheless.

I haven't really announced it but we are using it internally for a handful of project and I know former colleagues of mine using it at their companies as well.

Jonathan

[Jim Fulton]

On Sat, Feb 11, 2017 at 9:51 AM, Jonathan Ballet <j...@multani.info> wrote:

On February 11, 2017 3:31:02 PM CET, Jim Fulton <j...@jimfulton.info> wrote:

>I'm thinking of a script akin to the bootstrap script that builds a
>virtualenv and uses it to create a buildout.  This has been suggested
>before, and I've resisted, but I'm coming around.  Does anyone know of
>such
>a script that they'd recommend?  If not, I'll start by documenting a
>fictional script initially. (I love science fiction.)

I will ago, I wrote this : https://github.com/multani/buildout-bootstrap-virtualenv

This actually worked quite well until latest setuptools release and I didn't have the chance to put a proper fix but you may be interested nevertheless.

Thanks. I'll check it out.

Jim

[Jim Fulton]

BTW, is anyone interested in reviewing changes?

If so, I'll make PRs going forward.

Another opportunity to contribute will be in writing "topics".

Jim

[Leonardo Rochael Almeida]

Hi Jim,

I'd be interested in reviewing whatever docs and changes you write.

In general, I agree with you that buildout should focus more on automation than packaging, but there is a lot that buildout and zc.recipe.egg do right regarding python package installation and `bin/` script generation, in my opinion, that cannot be replaced simply by automating subprocess calls to pip (at least not as pip stands right now).

And I also think we should keep in mind the reasonably large ecosystem of packages that extend `zc.recipe.egg` and kind-of relies on the way it behaves. Packages like `plone.recipe.zope2instance` or `anybox.recipe.odoo`.

I'll comment in lenght your original message later when I get some more time.

Thanks for investing your time on this!

Cheers,

--
You received this message because you are subscribed to the Google Groups "Buildout Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to buildout-development+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Jim Fulton]

On Mon, Feb 13, 2017 at 7:58 AM, Leonardo Rochael Almeida <leoro...@gmail.com> wrote:

Hi Jim,

I'd be interested in reviewing whatever docs and changes you write.

In general, I agree with you that buildout should focus more on automation than packaging, but there is a lot that buildout and zc.recipe.egg do right regarding python package installation and `bin/` script generation, in my opinion, that cannot be replaced simply by automating subprocess calls to pip (at least not as pip stands right now).

Agreed.  I was happy to realize this weekend that wheels potentially breath new life into this approach, because they avoid building at install time.

 

And I also think we should keep in mind the reasonably large ecosystem of packages that extend `zc.recipe.egg` and kind-of relies on the way it behaves. Packages like `plone.recipe.zope2instance` or `anybox.recipe.odoo`.

Yup.

 

I'll comment in lenght your original message later when I get some more time.

Thanks.

 

Thanks for investing your time on this!

I think it's potentially a modest effort that can do a lot of good.  I likely won't get back to writing new docs until this coming weekend. (I took a break from my current ZODB focus.)

It was in thinking about the getting started section that I was motivated to try the wheel thing.

My hope is that I can write a getting started section, a further details section and a couple of "topics" and that then some others might feel comfortable pitching on on additional topics.

Jim

[Theuni]

Hi,

catching up slowly ...  :)

I'm doing self-bootstrapping with virtualenv in batou. Here's the bootstrap script: 

https://bitbucket.org/flyingcircus/batou/src/c474d9d71569a87ec4db9266cf70d4e67e45beaf/src/batou/bootstrap-template?at=default&fileviewer=file-view-default

virtualenv isn't as nice as I'd want it to be, specifically when trying to move a once installed forward. However, this works for us quite well and hasn't broken for at least 1-2 years, I think. Also note that this is self-updating, so you can ask batou to upgrade and it will provide you with a new bootstrap script.

Also, I decided to make the bootstrap script the "single point of entry" - independent of whether you're bootstrapping or actually running. I consider that to have been a force that required us to make it robust enough and not be the 1% edge case that only hits new developers. It also keeps everyone in sync. I also decided that this virtualenv is not under the user's control and thus moved it to .batou to make it invisible. You can inject additionaly dependencies to that virtualenv by providing a 'requirements.txt'.

This probably isn't that glorious but it works. :) 

Christian