doc/dev/documenting.txt
author julien tayon <julien.tayon@logilab.fr>
Tue, 11 Jun 2019 09:40:12 +0200
changeset 12640 de1c0721656e
parent 10495 5bd914ebf3ae
child 12792 e2cdb1be6bd9
permissions -rw-r--r--
Fix sorting key for rdefs in schema viewer With changeset 234ca3cbbb46, clicking in the schema of an entity with cubicweb in py3 on "vue en boite" will probably result in an infinite spinner (which implies cw > 3.26) What happened ? This "vue en boite" used to work at least until... hg diff -c a8c1ea390400 cubicweb/schema.py @@ -993,10 +992,6 @@ class CubicWebRelationSchema(PermissionM return False return True - @deprecated('use .rdef(subjtype, objtype).role_cardinality(role)') - def cardinality(self, subjtype, objtype, target): - return self.rdef(subjtype, objtype).role_cardinality(target) - class CubicWebSchema(Schema): """set of entities and relations schema defining the possible data sets But, wait ... If I open a shell on an instance of cw 3.24 something seems off >>> list(schema['CWUniqueTogetherConstraint'].relation_definitions())[0][0].cardinality # <bound method CubicWebRelationSchema.wrapped of <constraint_of [CWUniqueTogetherConstraint,CWEType]>> We have been sorting on a method the whole time ? Is it possible what were the effects ? 1) We cannot sort function can't we ? >>> def adder(i): return lambda x: x+i >>> sorted(map(adder,range(10))) [<function __main__.<lambda>>, <function __main__.<lambda>>, ... Yes we can. 2) what does it means. >>> { adder(1) : 1 } Out[19]: {<function __main__.<lambda>>: 1} In fact the function object as a __hash__ method (which is practical for making memoizers (cache)), and return truly random results (pseudo random). My take on this patch is relations have NEVER been sorted by cardinality. No one never ever noticed. Hence, I propose to not fix a bug that never was reported.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
====
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
Book
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
====
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
----
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     6
Part
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     7
----
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     8
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     9
Chapter
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    10
=======
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    11
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    12
.. _Level1AnchorForLaterReference:
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    13
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    14
Level 1 section
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    15
---------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    16
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    17
Level 2 section
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    18
~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    19
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    20
Level 3 section
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    21
```````````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    22
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    23
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    24
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    25
*CubicWeb*
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    26
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    27
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    28
inline directives:
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    29
  :file:`directory/file`
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    30
  :envvar:`AN_ENV_VARIABLE`
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    31
  :command:`command --option arguments`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    32
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    33
  :ref:, :mod:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    34
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    35
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    36
.. sourcecode:: python
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    37
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    38
   class SomePythonCode:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    39
     ...
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    40
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    41
.. XXX a comment, wont be rendered
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    42
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    43
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    44
a [foot note]_
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    45
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    46
.. [foot note] the foot note content
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    47
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    48
6301
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    49
Boxes
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    50
=====
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    51
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    52
- warning box: 
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    53
    .. warning::
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    54
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    55
       Warning content
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    56
- note box:
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    57
    .. note::
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    58
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    59
       Note content
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    60
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    61
d9d6bdd814ba imported patch doc_test_commit.diff
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6245
diff changeset
    62
6245
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    63
Cross references
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    64
================
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    65
6245
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    66
To arbitrary section
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    67
--------------------
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    68
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    69
:ref:`identifier` ou :ref:`label <identifier>`
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    70
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    71
Label required of referencing node which as no title, else the node's title will be used.
4438
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    72
91e224154f11 more stuff in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1714
diff changeset
    73
6245
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    74
To API objects
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    75
--------------
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    76
See the autodoc sphinx extension documentation. Quick overview:
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    77
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    78
* ref to a class: :class:`cubicweb.devtools.testlib.AutomaticWebTest`
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    79
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    80
* if you can to see only the class name in the generated documentation, add a ~:
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    81
  :class:`~cubicweb.devtools.testlib.AutomaticWebTest`
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    82
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    83
* you can also use :mod: (module), :exc: (exception), :func: (function), :meth: (method)...
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    84
e7e9d73d0c07 [doc] add note about x-ref in doc's README
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4438
diff changeset
    85
* syntax explained above to specify label explicitly may also be used