Refactore docs and fix some issues #329
Conversation
|
@svx i tried to fix some issues and reorganized the content a bit. |
docs/index.rst
Outdated
|
|
||
| Add-ons created with ``bobtemplates.plone`` are tested to work in Plone 4.3.x and Plone 5. | ||
| Addon's created with ``bobtemplates.plone`` are tested to work in Plone 4.3.x and Plone 5. |
| `Title <http://link>`_ | ||
| ============ | ||
| content_type | ||
| ============ |
There was a problem hiding this comment.
but in this case it's the name of the template, that's why i wouldn't use a different way of writing here.
I also use it to gerate the list of templates and they should have the correct names.
On other places I'll try to take this into account. thx
docs/templates/addon/index.rst
Outdated
| @@ -0,0 +1,22 @@ | |||
| ===== | |||
| addon | |||
docs/templates/addon/index.rst
Outdated
|
|
||
| .. topic:: Description | ||
|
|
||
| Creating an addon package and extending it with subtemplates. |
docs/templates/addon/theme/index.rst
Outdated
| Creating a Plone theme inside a package | ||
| ======================================= | ||
| ===== | ||
| theme |
docs/templates/addon/theme/index.rst
Outdated
|
|
||
| .. topic:: Description | ||
|
|
||
| Adding a theme to an existing addon package. |
| @@ -0,0 +1,34 @@ | |||
| ================= | |||
| theme_barceloneta | |||
There was a problem hiding this comment.
Same here, you use it in a heading, so it should be Theme Barceloneta, always remember these are docs, not code, even if we preach docs as code, this does not mean we write docs like we write code :)
|
|
||
| .. topic:: Description | ||
|
|
||
| Adding a barceloneta theme to an existing addon package. |
|
|
||
| With this ``subtemplate``, you can add a Plone theme to a Plone package. | ||
|
|
||
| First create a Plone Addon Package: |
|
|
||
| First create a Plone Addon Package: | ||
|
|
||
| .. code-block:: sh |
There was a problem hiding this comment.
please use .. code-block:: shell
This is also written in our styleguide -> https://docs.plone.org/about/contributing/rst-styleguide.html :)
|
|
||
| then change into the created folder ``plonetheme.blacksea`` and your theme: | ||
|
|
||
| .. code-block:: sh |
| Adding a vocabulary | ||
| =================== | ||
| ========== | ||
| vocabulary |
|
|
||
| .. topic:: Description | ||
|
|
||
| Adding a vocabulary to an existing addon package. |
docs/templates/buildout/index.rst
Outdated
| Create Plone buildout package | ||
| ============================= | ||
| ======== | ||
| buildout |
| Creating a Plone theme package | ||
| ============================== | ||
| ============= | ||
| theme_package |
|
Please, please do not use more than one toctree, we are checking for multiple toctrees and tests are setup so that they fail if we detect more than one. There is almost never a reason to use more than one, by using more than one you make your docs structure more complicated than it has to be and also multiple toctress are not playing nice which each other, we had that in the training docs and it was "hell" to solve, it took me almost a week and other people had already given up on that. One common tip for structure docs, think "easy" and "flat". This is not code. Think who your audience is. I went now 2 times of the whole bobtemplates docs, and there is serious no reason to use more than one toc and also as soon as I have one evening where I bored I will restructure the whole docs of this repo, if that is ok with everyone. |
|
Thx for your advice. I thought with the second doctree we can solve the problem of having to update the docs on multible places, when ever we add a template. But if that makes trouble, I'll change it to normal a list of links. That means I can also change the writing of the headings as you suggested. About restructuring the docs, maybe we can do it together. |
|
Ok I've updated the docs again. Fell free to review it again. |
No description provided.