Some confusing points in the documentation

[philgyford]

Thanks for this - it seems great!

I had a few points of confusion with the documentation, not helped by this being the first thing I looked at on a Monday morning!

1. I'm not sure how to resolve this, but in Django Settings I was confused by the name of the WAGTAIL_CACHE_BACKEND setting. As I understand it, this isn't the name of a backend, but the name of the cache. e.g. I initially thought it should be set to "django-redis" or "memecached", because these are backends. But it looks like it should actually be a key from the CACHES setting? Using the term "backend" in the setting name, and its description on this page, is a bit confusing.

2. In Installation, under Use the cache decorator, a couple of things weren't immediately clear to me, and could be more explicit:

   1. When the first example says:

      # Replace:
      # url(r'', include(wagtail_urls)),
      
      # With:
      [several lines of code]

      should that initial url(... line be replaced with everything beneath # With:, or only with the four lines of imports? And then the rest of the example is additional code? It would be clearer to have two code samples: "before" (standard Wagtail) and "after" (using wagtail-cache).

   2. I was initially confused by the difference between the instructions to change urls.py, which is under a paragraph about using the decorator "on any views or URLs". And the second code example. Should we use both examples? One or the other? I now assume that the first example only caches children of the wagtail Page class, while the second caches standard Django views. Maybe this could be more explicit for those of us fairly new to Wagtail and/or slow on the uptake? :)

3. Following the instructions for Use the cache decorator I got this error, using Django 2.1:

   AttributeError: module 'django.contrib.auth.views' has no attribute 'login'

   It looks like this was deprecated, and then removed in Django 2.1. I think auth_views.login should be replaced with auth_views.LoginView.as_view().

4. It would be useful, alongside the instructions for decorating a view method, to show how to decorate a class-based view. I guess it's something like:

   from django.utils.decorators import method_decorator
   from wagtailcache.cache import cache_page
   
   @method_decorator(cache_page, name='dispatch')
   class MyListView(ListView):
       ...

[vsalvino]

Thanks for the feedback Phil. Feel free to make a pull request with doc updates, it would be appreciated.

For number 1, I agree with you. Unfortunately Django does not have a name for what those are, only refers to them as a "cache", which is an extremely general term to use for a package that does caching. Perhaps "cache definition" would be a good way to say it. You are correct though, it is not a literal backend but a cache definition in the CACHES = {} setting.

For number 3 above, the issue stems from the fact the urls.py needs to be a direct copy of wagtail's urls.py (which you referenced in number 2 as well). Unfortunately that is the one "clunky" thing that must be done because wagtail provides all of those URLs in one module, but we only want to cache the serve_page url. That could be better documented to remain compatible with future wagtail versions.

For number 4, I have not actually used tried this with class-based views yet. It should work in theory. If you made it work successfully, then I would really appreciate a pull request documenting the sample code.

[philgyford]

I'm happy to make a pull request... I just can't quite work out how to build the docs, having rarely used sphinx. I have it installed but can't work out what command to use, and from where...

[vsalvino]

Clone repo. Then pip install sphinx. Edit rst files in docs directory.

To build and confirm your edits look good:

cd docs/
make clean
make html

Output will be in docs/_build/html/ directory.

[philgyford]

Many thanks. I'm getting there, but make html from within the docs directory gets me:

Traceback (most recent call last):
  File "/Users/phil/.pyenv/versions/3.6.6/lib/python3.6/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/Users/phil/.pyenv/versions/3.6.6/lib/python3.6/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/Users/phil/Projects/other/wagtail-cache/docs/conf.py", line 19, in <module>
    from wagtailcache import __shortversion__
ModuleNotFoundError: No module named 'wagtailcache'

Have I missed a step?

[vsalvino]

Oops, I should have clarified. From the root git directory (wagtail-cache/) do pip install -e ./[dev] which will install the package and all of the development extras.

[philgyford]

Thanks for your patience - I got there in the end :)