update configuration rst docs and supporting files

update configuration rst docs and supporting files

Try to make moin configuration easier for users, add files so developers can easily test different configurations.

[RogerHaase, 2015-03-02 21:33:27]

Best place to start is by reviewing configure.rst.

Current docs leave it up to the user to create one or more directories for their
customizations. Idea is to create an empty wiki_local_data directory for custom
changes. Goal is to make it easier to document and support.

Added code to wikiconfig.py so user can just uncomment, hopefully causing fewer
errors than copy and paste.

Added wikiconfig_editme.py to contrib/. Hopefully developers will try testing
different configurations.

https://codereview.appspot.com/208070043/diff/60001/contrib/wikiconfig/wikico...
File contrib/wikiconfig/wikiconfig_editme.py (right):

https://codereview.appspot.com/208070043/diff/60001/contrib/wikiconfig/wikico...
contrib/wikiconfig/wikiconfig_editme.py:1: # -*- coding: utf-8 -*-
idea of adding this file and next is to make it easier for developers to try
different configurations

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst
File docs/admin/configure.rst (left):

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:1001: Dict backend configuration
currently dicts are not used by moin - seems confusing to document dicts in
configuration.

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py
File wikiconfig.py (left):

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#oldcode45
wikiconfig.py:45: )
moved down to ~110

trying to make sequence more logical

[Thomas.J.Waldmann, 2015-04-14 14:00:49]

https://codereview.appspot.com/208070043/diff/60001/contrib/wikiconfig/wikico...
File contrib/wikiconfig/wikiconfig_editme.py (right):

https://codereview.appspot.com/208070043/diff/60001/contrib/wikiconfig/wikico...
contrib/wikiconfig/wikiconfig_editme.py:1: # -*- coding: utf-8 -*-
On 2015/03/02 21:33:26, RogerHaase wrote:
> idea of adding this file and next is to make it easier for developers to try
> different configurations

I'ld rather not do it that way. If we make changes in moin, requiring different
configuration, we would always have to care for keeping both files in sync (and
they WILL get out of sync sooner or later).

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst
File docs/admin/configure.rst (left):

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:1001: Dict backend configuration
Maybe rather mention this, but don't kill it completely.

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst
File docs/admin/configure.rst (right):

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:72: wiki-local-data/          # a convenient location
to store custom CSS, Javascript, templates, logos, etc.
maybe just wiki-local (no "-data")?

in general, if this is a repo checkout, it is a bit dirty to have local data
inside here, the vcs will always complain about it and it may happen that
somebody even commits local stuff.

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:127: logo images, CSS, etc. To accomplish this, a
directory named "wiki_local_data"
decide & be consistent - either minus or underscore.

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:135: template_dirs = [os.path.join(wikiconfig_dir,
'wiki_local_data'), ]
will this use a "templates" directory below that directory? or the given
directory itself?

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:152: `wiki_local_data` and change the logo macro to
something like::
maybe there should be some structure below this dir:

wiki_local_data/templates/
wiki_local_data/htdocs/

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:855:
u"SuperMan,WonderWoman:read,write,create,destroy,admin All:read,write"
hah! :D

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:889: * For most wikis, the configured ACL rules will be
sufficient to protect most items.
maybe we should remove that completely.
might give a false sense of security.

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:900: it is rarely used.
please remove this again.

+ is not the default, the default is to stop on first username-only match.

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py
File wikiconfig.py (right):

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#newcode35
wikiconfig.py:35: #     wiki-local-data/          #
serve_files[wiki_local_data]: optional, store custom CSS, Javascript, templates,
logos, etc.
. or : at the end.

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#newcode53
wikiconfig.py:53: # we must add entries for 'Self' and our interwikiname, change
these if you are not running the built-in destop server:
typo "desktop"

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#newcode60
wikiconfig.py:60: # default is theme is basic
-is

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#newcode64
wikiconfig.py:64: # user_use_gravatar = True
this should not be here, but only in the docs, so admins also read the privacy
notice there.

[RogerHaase, 2015-05-30 19:44:48]

Your comment on WikiDicts was lost in most views comparing patchsets - I could
only see ti in base vs ps1.

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst
File docs/admin/configure.rst (left):

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:1001: Dict backend configuration
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> Maybe rather mention this, but don't kill it completely.

I spent quite some time trying to determine how to use WikiDicts for
configuration before deciding it could not be used. Does it have a current use?

Seems least confusing to drop it from the configuration docs for now and put it
back when it has a use. If you want to save this code we could remove it as a
separate patch or move it to wiki_dicts.py as a comment.

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst
File docs/admin/configure.rst (right):

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:72: wiki-local-data/          # a convenient location
to store custom CSS, Javascript, templates, logos, etc.
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> maybe just wiki-local (no "-data")?
> 
> in general, if this is a repo checkout, it is a bit dirty to have local data
> inside here, the vcs will always complain about it and it may happen that
> somebody even commits local stuff.

added directory to .hgignore

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:127: logo images, CSS, etc. To accomplish this, a
directory named "wiki_local_data"
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> decide & be consistent - either minus or underscore.

fixed, used _

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:135: template_dirs = [os.path.join(wikiconfig_dir,
'wiki_local_data'), ]
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> will this use a "templates" directory below that directory? or the given
> directory itself?

A guess is most installations will have only two files here: a logo image and
snippets.html. configure.rst tells how to create more subdirectories if needed.

Additional subdirectories will require more readme.txt files to ensure they are
created.

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:152: `wiki_local_data` and change the logo macro to
something like::
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> maybe there should be some structure below this dir:
> 
> wiki_local_data/templates/
> wiki_local_data/htdocs/

as above. 

htdocs?

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:889: * For most wikis, the configured ACL rules will be
sufficient to protect most items.
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> maybe we should remove that completely.
> might give a false sense of security.

done

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:900: it is rarely used.
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> please remove this again.
> 
> + is not the default, the default is to stop on first username-only match.

done, I learn something new

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py
File wikiconfig.py (right):

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#newcode35
wikiconfig.py:35: #     wiki-local-data/          #
serve_files[wiki_local_data]: optional, store custom CSS, Javascript, templates,
logos, etc.
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> . or : at the end.

fixed

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#newcode53
wikiconfig.py:53: # we must add entries for 'Self' and our interwikiname, change
these if you are not running the built-in destop server:
On 2015/04/14 14:00:49, Thomas.J.Waldmann wrote:
> typo "desktop"

fixed

https://codereview.appspot.com/208070043/diff/60001/wikiconfig.py#newcode64
wikiconfig.py:64: # user_use_gravatar = True
On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> this should not be here, but only in the docs, so admins also read the privacy
> notice there.

added note to read docs. This seems like a popular option, a goal should be to
make installation and configuration as easy as possible.

https://codereview.appspot.com/208070043/diff/120001/wikiconfig.py
File wikiconfig.py (right):

https://codereview.appspot.com/208070043/diff/120001/wikiconfig.py#newcode88
wikiconfig.py:88: # allow_style_attributes = True
anticipating that patch for #519 and #520 will eventually be OK.

Currently neither option nor docs exist

[Thomas.J.Waldmann, 2015-06-09 22:08:10]

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst
File docs/admin/configure.rst (right):

https://codereview.appspot.com/208070043/diff/60001/docs/admin/configure.rst#...
docs/admin/configure.rst:152: `wiki_local_data` and change the logo macro to
something like::
On 2015/05/30 19:44:47, RogerHaase wrote:
> On 2015/04/14 14:00:48, Thomas.J.Waldmann wrote:
> > maybe there should be some structure below this dir:
> > 
> > wiki_local_data/templates/
> > wiki_local_data/htdocs/
> 
> as above. 
> 
> htdocs? 

Acknowledged.

https://codereview.appspot.com/208070043/diff/120001/.hgignore
File .hgignore (right):

https://codereview.appspot.com/208070043/diff/120001/.hgignore#newcode16
.hgignore:16: ^MoinMoin/wiki_local/
didn't you mean:
wiki_local/  (not below MoinMoin/)
?

https://codereview.appspot.com/208070043/diff/120001/docs/admin/configure.rst
File docs/admin/configure.rst (right):

https://codereview.appspot.com/208070043/diff/120001/docs/admin/configure.rst...
docs/admin/configure.rst:72: wiki_local/               # a convenient location
to store custom CSS, Javascript, templates, logos, etc.
here it is not below MoinMoin/

https://codereview.appspot.com/208070043/diff/120001/wikiconfig.py
File wikiconfig.py (right):

https://codereview.appspot.com/208070043/diff/120001/wikiconfig.py#newcode7
wikiconfig.py:7: than a release package may opt to follow the developer
instructions below to
well, although we have a mercurial repository in .hg, i think it is more correct
to speak of a workdir - as the files we use are in the workdir, not in the
repository.

https://codereview.appspot.com/208070043/diff/120001/wikiconfig.py#newcode65
wikiconfig.py:65: }
dict() is for the lazy :)

[RogerHaase, 2015-06-12 14:51:51]

minor changes

https://codereview.appspot.com/208070043/diff/120001/.hgignore
File .hgignore (right):

https://codereview.appspot.com/208070043/diff/120001/.hgignore#newcode16
.hgignore:16: ^MoinMoin/wiki_local/
On 2015/06/09 22:08:09, Thomas.J.Waldmann wrote:
> didn't you mean:
> wiki_local/  (not below MoinMoin/)
> ?

oops