Skip to content

docs(ext): fix rendering for RequiredOptional and refer to upstream docs #2060

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
merged 2 commits into from
Jun 6, 2022
Merged

docs(ext): fix rendering for RequiredOptional and refer to upstream docs #2060

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e29b451
docs(ext): fix rendering for RequiredOptional dataclass
nejch Jun 6, 2022
9571c47
docs(usage): refer to upsteam docs instead of custom attributes
nejch Jun 6, 2022
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
26 changes: 12 additions & 14 deletions docs/api-usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,28 +102,26 @@ Examples:
for project in group.projects.list(iterator=True):
print(project)

# create a new user
user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
user = gl.users.create(user_data)
print(user)

.. warning::
Calling ``list()`` without any arguments will by default not return the complete list
of items. Use either the ``all=True`` or ``iterator=True`` parameters to get all the
items when using listing methods. See the :ref:`pagination` section for more
information.

You can list the mandatory, optional, and mutually exclusive attributes for object
creation and update with the manager's ``get_create_attrs()`` and ``get_update_attrs()``
methods. They return 3 tuples. The first tuple is the list of mandatory attributes.
The second tuple is the list of optional attributes. The third tuple is the mutually
exclusive attributes:

.. code-block:: python

# v4 only
print(gl.projects.get_create_attrs())
(('name',), ('path', 'namespace_id', ...))
# create a new user
user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
user = gl.users.create(user_data)
print(user)

.. note::
python-gitlab attempts to sync the required, optional, and mutually exclusive attributes
for resource creation and update with the upstream API.

You are encouraged to follow upstream API documentation for each resource to find these -
each resource documented here links to the corresponding upstream resource documentation
at the top of the page.

The attributes of objects are defined upon object creation, and depend on the
GitLab API itself. To list the available information associated with an object
Expand Down
20 changes: 10 additions & 10 deletions docs/ext/manager_tmpl.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,43 +7,43 @@

{% if cls._create_attrs %}
**Object Creation**
{% if cls._create_attrs[0] %}
Mandatory attributes for object create:
{% if cls._create_attrs.required %}
Required attributes for object create:
{% for item in cls._create_attrs.required %}
- ``{{ item }}``
{% endfor %}
{% endif %}
{% if cls._create_attrs[1] %}
{% if cls._create_attrs.optional %}
Optional attributes for object create:
{% for item in cls._create_attrs.optional %}
- ``{{ item }}``
{% endfor %}
{% endif %}
{% if cls._create_attrs[2] %}
{% if cls._create_attrs.exclusive %}
Mutually exclusive attributes for object create:
{% for item in cls._create_attrs.exlusive %}
{% for item in cls._create_attrs.exclusive %}
- ``{{ item }}``
{% endfor %}
{% endif %}
{% endif %}

{% if cls._update_attrs %}
**Object update**
{% if cls._update_attrs[0] %}
Mandatory attributes for object update:
{% if cls._update_attrs.required %}
Required attributes for object update:
{% for item in cls._update_attrs.required %}
- ``{{ item }}``
{% endfor %}
{% endif %}
{% if cls._update_attrs[1] %}
{% if cls._update_attrs.optional %}
Optional attributes for object update:
{% for item in cls._update_attrs.optional %}
- ``{{ item }}``
{% endfor %}
{% endif %}
{% if cls._update_attrs[2] %}
{% if cls._update_attrs.exclusive %}
Mutually exclusive attributes for object update:
{% for item in cls._update_attrs.exlusive %}
{% for item in cls._update_attrs.exclusive %}
- ``{{ item }}``
{% endfor %}
{% endif %}
Expand Down