Skip to content

Docs adoption for 2.0 #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rnixx merged 3 commits into from
Jan 23, 2026
Merged

Docs adoption for 2.0 #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
35d43a5
WIP: fix outdated docs
lenadax Jan 22, 2026
b9e16bf
fix more docs
lenadax Jan 22, 2026
d0500ae
add documentation for previously undocumented code.
lenadax Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/source/ajax.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,7 @@ a single or a list of continuation operation instances.
from cone.app.browser.ajax import ajax_continue
from cone.tile import Tile
from cone.tile import tile
from cone.app.browser.utils import make_url

@tile(name='exampleaction', permission='view')
class ExampleAction(Tile):
Expand All @@ -215,7 +216,7 @@ a single or a list of continuation operation instances.
)

# queue continuation operations
ajax_continue(request, [overlay, event])
ajax_continue(self.request, [overlay, event])
return u''

A shortcut for continuation message operations is located at
Expand Down
6 changes: 3 additions & 3 deletions docs/source/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ deployments.
- **cone.admin_password**: Password of superuser.

- **cone.authenticator**: Utility registration name of a
``cone.app.interfaces.IAuthenticator`` impementation.
``cone.app.interfaces.IAuthenticator`` implementation.


Authentication Policy Configuration
Expand Down Expand Up @@ -89,7 +89,7 @@ If desired, the concrete UGM implementation is created on application startup.
- **ugm.backend**: Registration name of UGM implementation.

A default file based UGM factory is registered under name ``file``, which
creates a ``cone.ugm.file.Ugm`` instance.
creates a ``node.ext.ugm.file.Ugm`` instance.

Configuration is done through the following parameters.

Expand Down Expand Up @@ -180,4 +180,4 @@ application config file:

- **cone.root.node_available**: Callable returning whether the node is allowed
to be used in this application. Gets passed the application model and a
node info instane as arguments.
node info instance as arguments.
5 changes: 3 additions & 2 deletions docs/source/development.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ Browser Resources

Included resources:

- https://github.com/twbs/bootstrap/releases/tag/v5.0.2
- https://github.com/twbs/icons/archive/v1.5.0.zip
- https://github.com/jquery/jquery/releases/tag/4.0.0-beta
- https://github.com/twbs/bootstrap/releases/tag/v5.3.3
- https://github.com/twbs/icons/releases/tag/v1.11.3
- https://github.com/corejavascript/typeahead.js/releases/tag/v1.3.1
5 changes: 3 additions & 2 deletions docs/source/forms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -709,6 +709,7 @@ form's ``save`` function.

from plumber import Behavior
from plumber import plumb
from yafowil.base import factory

class FormExtension(Behavior):
"""Plumbing behavior used as form extension.
Expand All @@ -730,12 +731,12 @@ form's ``save`` function.
})
# add new widget before save widget
save_widget = self.form['save']
self.form.insertbefore(roles_widget, save_widget)
self.form.insertbefore(widget, save_widget)

@plumb
def save(_next, self, widget, data):
# fetch extension field value from form data
value = data.fetch('%s.generic' % self.form_name).extracted
value = data.fetch('%s.generic' % self.form.name).extracted
# set extracted value to model attributes
self.model.attrs['generic'] = value
# call downstream ``save`` function
Expand Down
32 changes: 28 additions & 4 deletions docs/source/layout.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,30 @@ file::
cone.main_template = cone.example.browser:templates/main.pt


Rendering the Main Template
---------------------------

To render a view using the main template, use ``render_main_template`` from
``cone.app.browser``.

.. code-block:: python

from cone.app.browser import render_main_template
from pyramid.view import view_config

@view_config(name='myview', permission='view')
def myview(model, request):
# Renders main template with 'mycontent' tile in content area
return render_main_template(model, request, 'mycontent')

Parameters:

- **model**: The application model node.
- **request**: The current request object.
- **contenttile**: Name of the tile to render in the content area. Defaults
to ``'content'``.


Application Layout
------------------

Expand Down Expand Up @@ -67,10 +91,10 @@ one or more model classes with ``cone.app.layout_config`` decorator.
pass

@layout_config(CustomNodeOne, CustomNodeTwo)
class CustomLayoutConfig(LayoutConfig)
class CustomLayoutConfig(LayoutConfig):

def __init__(self, model, request):
super(ExampleNodeLayoutConfig, self).__init__(model, request)
super(CustomLayoutConfig, self).__init__(model, request)
self.mainmenu = True
self.livesearch = True
self.personaltools = True
Expand Down Expand Up @@ -131,14 +155,14 @@ one or more model classes with ``cone.app.layout_config`` decorator.
added to specify sidebar modes (either ``'stacked'`` or ``'toggle'``).
- The ``limit_content_width`` setting has been added to replace the former
``columns_fluid`` setting.
- As of version 2.0, ``limit_content_width`` defaults to ``False``.
- As of version 2.0, ``limit_content_width`` defaults to ``True``.

.. version-removed:: 2.0

``mainmenu_fluid``, ``columns_fluid``, ``sidebar_left_grid_width`` and
``content_grid_width`` have been removed in ``cone.app 2.0`` in favor of a
more flexible layout.
Use the ``columns_fluid`` setting instead to limit content width on
Use the ``limit_content_width`` setting instead to limit content width on
large screens.

.. deprecated:: 1.1
Expand Down
43 changes: 33 additions & 10 deletions docs/source/model.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,24 @@ used to serve the entry nodes of the application.
return BaseNode()


LeafNode
--------

The ``cone.app.model.LeafNode`` behavior is used for application model nodes
that cannot have children. It disables child-related operations.

.. code-block:: python

from cone.app.model import BaseNode
from cone.app.model import LeafNode
from plumber import plumbing

@plumbing(LeafNode)
class DocumentNode(BaseNode):
"""A node that cannot contain children."""
pass


AdapterNode
-----------

Expand Down Expand Up @@ -296,7 +314,7 @@ Available properties are provided by ``keys`` function.

>>> from cone.app.model import Properties

>>> props = Properties
>>> props = Properties()
>>> props.a = '1'
>>> props.b = '2'
>>> props.keys()
Expand Down Expand Up @@ -362,7 +380,7 @@ property, ``ProtectedProperties`` behaves as if this property is inexistent.
Metadata
--------

``cone.app.model.Metadada`` class inherits from ``cone.app.model.Properties``
``cone.app.model.Metadata`` class inherits from ``cone.app.model.Properties``
and adds the marker interface ``cone.app.interfaces.IMetadata``. This object
is for ``cone.app.interfaces.IApplicationNode.metadata``.

Expand Down Expand Up @@ -510,18 +528,23 @@ Node Availability
~~~~~~~~~~~~~~~~~

The ``node_available`` callback can be used to control whether a registered
node type is available in the application context:
node type is available in the application context.

.. code-block:: python
The callback is configured via the application ini file:

from cone.app.model import node_available
.. code-block:: ini

cone.root.node_available = my.package.check_node_available

The callback function must have the following signature:

.. code-block:: python

@node_available
def check_node_available(node_info, container):
"""Return True if node type should be available for the container.
def check_node_available(model, node_info_name):
"""Return True if node type should be available.

:param node_info: The NodeInfo instance
:param container: The parent container where node would be added
:param model: The application node to gain access to the application model.
:param node_info_name: The node info name of the node to check availability.
:return: Boolean indicating availability
"""
# Custom logic to determine availability
Expand Down
6 changes: 3 additions & 3 deletions docs/source/plugins.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ Plugin root node factories are registered to the application via

from cone.app import main_hook
from cone.app import register_entry
import cone.example.model import ExamplePlugin
from cone.example.model import ExamplePlugin

@main_hook
def example_main_hook(config, global_config, settings):
Expand Down Expand Up @@ -180,7 +180,7 @@ and registered via ``cone.app.register_config``.
name='example_settings',
title='Example Settings',
description='Settings for the example plugin',
icon='glyphicon glyphicon-cog')
icon='bi bi-gear')
class ExampleSettings(SettingsNode):
"""Plugin settings node."""
# Category for grouping in settings UI
Expand Down Expand Up @@ -223,7 +223,7 @@ settings should be editable by users without ``manage`` permission.

.. note::

As of version 1.1, settings are accessible to authenticated users, not just
Since version 1.1, settings are accessible to authenticated users, not just
managers. The ``display`` property on ``SettingsNode`` controls visibility
per settings node.

Expand Down
38 changes: 28 additions & 10 deletions docs/source/quickstart.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ Register the resources in ``src/cone/example/browser/__init__.py``:
)
cone_example_resources.add(wr.ScriptResource(
name='cone-example-js',
depends='cone-app-protected-js',
depends='cone-app-js',
resource='example.js'
))
cone_example_resources.add(wr.StyleResource(
Expand Down Expand Up @@ -348,22 +348,40 @@ user interface. The documentation how to properly integrate custom JavaScript
into Ajax SSR can be found :ref:`here <ajax_custom_javascript>`.


9. Installation
---------------
9. Run Application
------------------

To install the application, create and activate the virtual environment:
After creating the virtual environment as described in section 2, run the
application:

.. code-block:: sh

python3 -m venv venv
./venv/bin/pip install -e .
./venv/bin/pserve example.ini

The application is now available at ``localhost:8081``.

10. Run Application
-------------------

Advanced: Using mxmake
----------------------

For larger projects, consider using `mxmake <https://mxmake.readthedocs.io>`_
to manage your build process. mxmake generates a Makefile with common
development tasks.

With mxmake, you get convenient make targets:

- ``make install`` - Create virtual environment and install dependencies
- ``make test`` - Run tests
- ``make coverage`` - Run tests with coverage
- ``make docs`` - Build Sphinx documentation
- ``make lingua`` - Extract and compile translations
- ``make clean`` - Clean build artifacts

To set up mxmake for your plugin:

.. code-block:: sh

./venv/bin/pserve example.ini
pip install mxmake
mxmake init

The application is now available at ``localhost:8081``.
See the ``cone.app`` repository for an example mxmake configuration.
Loading
Loading