[Rest2web-develop] Re: rest2web

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Robert Brewer wrote:
> Fuzzyman,
>
> Sorry it's taken me a while to get back, I got swamped for a bit
> and felt I should take a peek before replying.
>   

No problem. I'd be happier having this conversation on the 
rest2web-develop mailing list (you can sign up via sourceforge). It's 
quite low traffic, but then the discussion gets archived and other users 
can chip in if they want to.
> I am definitely willing to discuss how to get rest2web a little
> more toward my bent... :)  I got your second email on the subject
> about the uservalues.  I think that is on the right track, though I'd
> hope to go even further as I'll explain below.
>
> At the time I put the first cut of my website up I found that a couple
> tweaks to docutils and a makefile were enough to get me started.
> Obviously rest2web has plenty more features that I'd
> rather not even try to duplicate.
>
> Just for grins, I'll lay out a few things I would like to see in the
> "ultimate reST to website tool".  I'm not sure how these may fit
> with your vision of rest2web, but it can give us some start for discussion. :)
>
> 1. Super simple on the low end.  It'd be great to just put reST files
> in a directory hierarchy, press go, and have a website created
> with nice breadcrumbs, navbars, and all that stuff.  The tool
> would have defaults in this case, such as making the breadcrumbs
> follow directory names and page names or something like that.
>   
I've done a first cut of this - see rest2web-0.5.0alpha :

    http://www.voidspace.org.uk/rest2web-0.5.0alpha.zip

There are rough notes on some of the changes at :

    http://www.voidspace.org.uk/python/weblog/arch_d7_2006_04_22.shtml#e309

The thing to do is just give it a source directory of rest files and run 
``r2w.py --force`` at the command line. :-)

Please give me feedback. Currently you can't specify template files, but 
can modify the default ones supplied in the rest2web directory.

I'd like feedback on :

    Page crumbs
    Index crumbs
    Index titles

There should be a simple test directory included in the new zipfile 
which illustrates  the source and output...

> This may or may not work well in practice, but maybe it could even notice a
> directory full of .jpg files and create a simple gallery for that
> directory.  
That's harder but not impossible.

Again I'd need to supply a default template for the gallery pages *and* 
the gallery index page, and it would need to copy all the jpgs into the 
target directory.

The part that makes it fiddly is that the user might want control over 
any individual step in that process (supply an index page source file, 
but no page template - or the other way round) so it gets fiddly to 
allow full customisation.

It also means proper communication with the gallery plugin. At the 
moment the plugin system is very rough as the gallery is basically the 
only plugin.

I'm happy to get there (would be even happier if someone else was 
working on it to), but it may take a while to get right...

> In another case, if there is no index.txt or index.html
> in a directory, it may take it upon itself to create an index.txt (in reST,
>   
I'd rather just generate default HTML than generate a rest file as an 
intermediate step. Effectively all index pages will use the same source 
file, as there are standard functions for generating links to every page 
in a directory.

> subsequently translated to HTML) with a bulleted
> list of links to all files and subdirectories in that directory.  The user
> may specify some CSS and reST/HTML header/footer files that
> have global applicability for the generated website.
>   
Ok, something like this needs to be worked in. You're effectively 
describing a template page though - one that looks like :

<html>
<head><title><% title %></title>
... CSS links etc ...
</head>
<body>
<% body %>
</body>
</html>

You can now pass in a template file at the command line, or in force 
mode use the default one.

I don't see any need to split this up into header/footer chunks etc.

> 2. Customizable for the more advanced stuff.  The user can
> make config files to tweak these defaults, such as making
> a more user-friendly breadcrumb name than the directory name,
> or a page description for the index pages, etc.  Basically the
> tweaks you have in the restindex.
>
>   
Ok - we can work on this, maybe configure the defaults. Or are you 
asking for an external config file to specify crumb names for individual 
pages ?

> Number 1 basically says that I don't have to maintain any metadata
> if I don't want to.  For most of my website that would be fine.
Well - we've got something that behaves like that now.

I think it will take some work to get the auto-generated index pages 
looking good.

>   In my
> website directory I could create some symlinks to the documentation
> directories of the projects I want to publish.  
Interesting - do you know if ``os.path.isdir(pathname)`` returns 
``True`` for a symbolic link ? I wonder if I'd need to include any code 
to handle it ?

It could be a useful feature... I'll only add this if you promise to use 
it though. ;-)

> When I press go their latest
> reST files get converted and added into the main site with a seamless navbar
> and breadcrumb system.  I could easily add some pictures by adding
> symlinks to some of my photo directories.  This lets me add, rearrange,
> and remove stuff from the website with almost no effort. 
As mentioned before - certainly possible, details to sort.

Lets see where this takes us.

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

>  Just a few
> filesystem commands and then I press go to regenerate.
> As an example, the "projects" page on my site
> http://brewer123.home.comcast.net/projects/
> could be autogenerated as a bulleted list of links
> to each subdirectory.  Sure, it wouldn't have the text about
> "Here are some projects I've done and am releasing publicly"
> and it wouldn't have the little descriptions of some of the projects.
> But I might not even care about those things if it was autogenerated
> with "zero effort".  :)
>
> Some front pages of the website I may want to look a little nicer
> and be a little friendlier, so I use the config files to create some
> better metadata.  And if I have time and inclination, I can do that
> for the projects with the symlinks too, but I don't have to.
>
> So that's why I wasn't liking the having the restindex be part of
> the file, or even required at all for generating a page.  It's because
> I want to just plop a directory of reST files in my website directory and have
> it become part of my website.
>
> Well, this got a little longer and possibly more confusing than
> I expected.  Ask away if I'm not being clear.  I guess my personal
> desire is for a way to turn a directory hierarchy into a useful
> website with as little effort as possible.  Even with a hodge-podge
> of file types in the hierarchy.  And once the "zero-effort" website
> is created, it should be possible to spruce it up a bit by manually
> providing metadata to the tool and regenerating.
>
> By the way, the new look to your rest2web pages is very nice.
> I like it a lot.
>
> Thanks for opening the discussion, I'm looking forward to your
> thoughts...
>
> -Rob
>
> On 3/31/06, Michael Foord <fuz...@vo...> wrote:
>   
>> Hello Rob,
>>
>> I saw on your website that you considered rest2web, but couldn't use it
>> because of the restindex metadata stored in each page.
>>
>> I wondered if you wanted to explore a way round that with me ?
>>
>> If you are still interested we can bandy around a few ideas to come up
>> with something that works for you.
>>
>> Fuzzyman
>> (Michael Foord)
>> http://www.voidspace.org.uk/python/index.shtml
>>
>>     
>
>
> --
> Robert W. Brewer
>
>   