Skip to content
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

Jump to bottom

sphinx: enable nit-picky mode #570

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

sphinx: enable nit-picky mode #570

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 5 additions & 5 deletions build_requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Sphinx==5.0.1
furo==2022.6.4.1
myst-parser==0.18.0
sphinx-copybutton==0.5.0
sphinx-design==0.5.0
Sphinx==7.0.1
furo==2023.09.10
myst-parser==3.0.0
sphinx-copybutton==0.5.2
sphinx-design==0.6.1
m2r2==0.3.2
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Were these particular versions selected for a reason, apart from their (possibly) being the most recent in a package manager? If there's no real reason for these particular versions, would it make sense to take your package manager's (conda, pip) default? Taking the defaults would spare us maintaining hard-coded versions.

2 changes: 1 addition & 1 deletion docs/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
html:
sphinx-build -b html ./source/ ./generated_docs/ -W --keep-going
sphinx-build -b html ./source/ ./generated_docs/ -W -n --keep-going
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to write a little bloc saying that you are building in "nit-picky" mode? Would we want "nit-picky" to be our default condition? If yes, then we're accepting the possibility of the mass of broken links outweighing the occurrence of spurious / unhelpful warnings / errors. Do we have any broken links : unhelpful warnings data?

python3 ./source/edit_button_handler.py

clean:
Expand Down
8 changes: 4 additions & 4 deletions docs/source/API/algorithms/std-algorithms/Iterators.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,19 @@ Iterators
Header File: ``<Kokkos_StdAlgorithms.hpp>``


.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto begin(const Kokkos::View<DataType, Properties...>& view);
.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto begin(const View<DataType, Properties...>& view);

Returns a Kokkos **random access** iterator to the beginning of ``view``

.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto cbegin(const Kokkos::View<DataType, Properties...>& view);
.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto cbegin(const View<DataType, Properties...>& view);

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are the changes in lines 13 and 17 "nit-picky" related, or are you just correcting errors you happened upon?

Returns a Kokkos const-qualified **random access** iterator to the beginning of ``view``

.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto end(const Kokkos::View<DataType, Properties...>& view);
.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto end(const View<DataType, Properties...>& view);

Returns a Kokkos **random access** iterator to the element past the end of ``view``

.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto cend(const Kokkos::View<DataType, Properties...>& view);
.. cppkokkos:kokkosinlinefunction:: template <class DataType, class... Properties> auto cend(const View<DataType, Properties...>& view);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are the changes in lines 13, 17, 21 and 25 "nit-picky" related, or are you just correcting errors you happened upon?


Returns a const-qualified Kokkos **random access** iterator to the element past the end of ``view``

Expand Down
65 changes: 34 additions & 31 deletions docs/source/API/core/view/view.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,9 @@ Its semantics are similar to that of ``std::shared_ptr``.
Interface
---------

.. code-block:: cpp
.. cppkokkos:class:: template <typename DataType> View
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice!


template <class DataType [, class LayoutType] [, class MemorySpace] [, class MemoryTraits]>
class View;
We should still describe DataType LayoutType MemorySpace MemoryTraits....
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean for line 17 to be part of the documentation, or is it intended as a "TODO"?


Parameters
~~~~~~~~~~
Expand Down Expand Up @@ -70,7 +69,7 @@ and ``MemoryTraits`` are specified, ``MemorySpace`` must come before ``MemoryTra

.. _Atomic: ../atomics.html

.. |Atomic| replace:: :cppkokkos:func:`Atomic`
.. |Atomic| replace:: :code:`Atomic`


* ``MemoryTraits``:
Expand Down Expand Up @@ -115,6 +114,10 @@ Typedefs

.. rubric:: Data Types

.. cppkokkos:type:: traits

To do.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the intent to provide a brief description of traits? If so, were you planning do it in this PR : )


.. cpp:type:: data_type

The ``DataType`` of the View, note ``data_type`` contains the array specifiers (e.g. ``int**[3]``)
Expand Down Expand Up @@ -195,11 +198,11 @@ Typedefs

.. rubric:: Data Handles

.. cpp:type:: reference_type
.. cppkokkos:type:: reference_type

return type of the view access operators.

.. cpp:type:: pointer_type
.. cppkokkos:type:: pointer_type

pointer to scalar type.

Expand All @@ -225,19 +228,19 @@ Typedefs
Constructors
~~~~~~~~~~~~

.. cppkokkos:function:: View()
.. cppkokkos:function:: View::View()

Default Constructor. No allocations are made, no reference counting happens. All extents are zero and its data pointer is NULL.

.. cppkokkos:function:: View( const View<DT, Prop...>& rhs)
.. cppkokkos:function:: template <class RT, class... RP> View::View( const View<RT, RP...>& rhs)

Copy constructor with compatible view. Follows View assignment rules.

.. cppkokkos:function:: View( View&& rhs)
.. cppkokkos:function:: View::View( View&& rhs)

Move constructor

.. cppkokkos:function:: View( const std::string& name, const IntType& ... indices)
.. cppkokkos:function:: View::View( const std::string& name, const IntType& ... indices)

Standard allocating constructor. The initialization is executed on the default
instance of the execution space corresponding to ``MemorySpace`` and fences it.
Expand All @@ -251,7 +254,7 @@ Constructors

- Requires: ``array_layout::is_regular == true``.

.. cppkokkos:function:: View( const std::string& name, const array_layout& layout)
.. cppkokkos:function:: View::View( const std::string& name, const array_layout& layout)

Standard allocating constructor. The initialization is executed on the default
instance of the execution space corresponding to ``MemorySpace`` and fences it.
Expand All @@ -263,7 +266,7 @@ Constructors
either match the dynamic rank or the total rank. In the latter case, the extents
corresponding to compile-time dimensions must match the View type's compile-time extents.

.. cppkokkos:function:: View( const ALLOC_PROP &prop, const IntType& ... indices)
.. cppkokkos:function:: View::View( const ALLOC_PROP &prop, const IntType& ... indices)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ALLOC_PROP: perhaps an opportunity to link to the forthcoming Glossary of terms championed by @nmm0 !


Allocating constructor with allocation properties (created by a call to `Kokkos::view_alloc`). If an execution space is
specified in ``prop``, the initialization uses it and does not fence.
Expand All @@ -278,7 +281,7 @@ Constructors

- Requires: ``array_layout::is_regular == true``.

.. cppkokkos:function:: View( const ALLOC_PROP &prop, const array_layout& layout)
.. cppkokkos:function:: View::View( const ALLOC_PROP &prop, const array_layout& layout)

Allocating constructor with allocation properties (created by a call to `Kokkos::view_alloc`) and a layout object. If an execution space is
specified in ``prop``, the initialization uses it and does not fence. Otherwise, the View is
Expand All @@ -290,7 +293,7 @@ Constructors
match the dynamic rank or the total rank. In the latter case, the extents corresponding
to compile-time dimensions must match the View type's compile-time extents.

.. cppkokkos:function:: View( pointer_type ptr, const IntType& ... indices)
.. cppkokkos:function:: View::View( pointer_type ptr, const IntType& ... indices)

Unmanaged data wrapping constructor.

Expand All @@ -303,7 +306,7 @@ Constructors

- Requires: ``array_layout::is_regular == true``.

.. cppkokkos:function:: View( pointer_type ptr, const array_layout& layout)
.. cppkokkos:function:: View::View( pointer_type ptr, const array_layout& layout)

Unmanaged data wrapper constructor.

Expand All @@ -314,7 +317,7 @@ Constructors
either match the dynamic rank or the total rank. In the latter case, the extents
corresponding to compile-time dimensions must match the View type's compile-time extents.

.. cppkokkos:function:: View( const ScratchSpace& space, const IntType& ... indices)
.. cppkokkos:function:: View::View( const ScratchSpace& space, const IntType& ... indices)

Constructor which acquires memory from a Scratch Memory handle.

Expand All @@ -327,7 +330,7 @@ Constructors

- Requires: ``array_layout::is_regular == true``.

.. cppkokkos:function:: View( const ScratchSpace& space, const array_layout& layout)
.. cppkokkos:function:: View::View( const ScratchSpace& space, const array_layout& layout)

Constructor which acquires memory from a Scratch Memory handle.

Expand All @@ -337,11 +340,11 @@ Constructors
either match the dynamic rank or the total rank. In the latter case, the extents
corresponding to compile-time dimensions must match the View type's compile-time extents.

.. cppkokkos:function:: View( const View<DT, Prop...>& rhs, Args ... args)
.. cppkokkos:function:: View::View( const View<DT, Prop...>& rhs, Args ... args)

Subview constructor. See ``subview`` function for arguments.

.. cppkokkos:function:: explicit(traits::is_managed) View( const NATURAL_MDSPAN_TYPE& mds )
.. cppkokkos:function:: explicit(traits::is_managed) View::View( const NATURAL_MDSPAN_TYPE& mds )
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a definition somewhere for NATURAL_MDSPAN_TYPE?


:param mds: the mdspan to convert from.

Expand All @@ -353,13 +356,13 @@ Constructors
:cpp:`NATURAL_MDSPAN_TYPE` is the :ref:`natural mdspan <api-view-natural-mdspans>` of the View. The *natural mdspan* is only available if :cpp:type:`array_layout` is one of :cppkokkos:struct:`LayoutLeft`, :cppkokkos:struct:`LayoutRight`,
or :cpp:class:`LayoutStride`. This constructor is only available if *natural mdspan* is available.

Constructs a :cpp:class:`View` by converting from :cpp:any:`mds`. The :cpp:class:`View` will be unmanaged and constructed as if by :cpp:`View(mds.data(), array_layout_from_mapping(mds.mapping()))`
Constructs a :cppkokkos:class:`View` by converting from :cpp:any:`mds`. The :cppkokkos:class:`View` will be unmanaged and constructed as if by :cpp:`View(mds.data(), array_layout_from_mapping(mds.mapping()))`

.. seealso:: :ref:`Natural mdspans <api-view-natural-mdspans>`

.. versionadded:: 4.4.0

.. cppkokkos:function:: template <class ElementType, class ExtentsType, class LayoutType, class AccessorType> explicit(SEE_BELOW) View(const mdspan<ElementType, ExtentsType, LayoutType, AccessorType>& mds)
.. cppkokkos:function:: template <class ElementType, class ExtentsType, class LayoutType, class AccessorType> explicit(SEE_BELOW) View::View(const mdspan<ElementType, ExtentsType, LayoutType, AccessorType>& mds)

:tparam ElementType: the mdspan element type
:tparam ExtentsType: the mdspan extents
Expand All @@ -373,11 +376,11 @@ Constructors
:cpp:`explicit(bool)` is only available on C++20 and later. When building Kokkos with C++17, this constructor will be fully implicit.
Be aware that later upgrading to C++20 will in some cases cause compilation issues in cases where the condition is false.

Constructs a :cpp:class:`View` by converting from :cpp:any:`mds`.
The :cpp:class:`View`'s :ref:`natural mdspan <api-view-natural-mdspans>` must be constructible from :cpp:any:`mds`. The :cpp:class:`View` will be constructed as if by :cpp:`View(NATURAL_MDSPAN_TYPE(mds))`
Constructs a :cppkokkos:class:`View` by converting from :cpp:any:`mds`.
The :cppkokkos:class:`View`'s :ref:`natural mdspan <api-view-natural-mdspans>` must be constructible from :cpp:any:`mds`. The :cppkokkos:class:`View` will be constructed as if by :cpp:`View(NATURAL_MDSPAN_TYPE(mds))`

In C++20:
This constructor is implicit if :cpp:any:`mds` is implicitly convertible to the *natural mdspan* of the :cpp:class:`View`.
This constructor is implicit if :cpp:any:`mds` is implicitly convertible to the *natural mdspan* of the :cppkokkos:class:`View`.

.. versionadded:: 4.4.0

Expand Down Expand Up @@ -484,7 +487,7 @@ types have a nullary member function (i.e. callable with no argument).

Returns the product of extents, i.e. the logical number of elements in the view.

.. cppkokkos:function:: constexpr pointer_type data() const
.. cppkokkos:function:: constexpr pointer_type View::data() const

Return the pointer to the underlying data allocation.
WARNING: calling any function that manipulates the behavior
Expand Down Expand Up @@ -517,7 +520,7 @@ Other

Returns the label of the View.

.. cppkokkos:function:: const bool is_assignable(const View<DT, Prop...>& rhs);
.. cppkokkos:function:: const bool is_assignable(const View<DataType, Properties...>& rhs);

Returns true if the View can be assigned to rhs. See below for assignment rules.

Expand Down Expand Up @@ -545,17 +548,17 @@ Conversion to mdspan
:tparam OtherLayoutPolicy: the target mdspan layout
:tparam OtherAccessor: the target mdspan accessor

:constraints: :cpp:class:`View`\ 's :ref:`natural mdspan <api-view-natural-mdspans>` must be assignable to :cpp:`mdspan<OtherElementType, OtherExtents, OtherLayoutPolicy, OtherAccessor>`
:constraints: :cppkokkos:class:`View`\ 's :ref:`natural mdspan <api-view-natural-mdspans>` must be assignable to :cpp:`mdspan<OtherElementType, OtherExtents, OtherLayoutPolicy, OtherAccessor>`

:returns: an mdspan with extents and a layout converted from the :cpp:class:`View`'s *natural mdspan*.
:returns: an mdspan with extents and a layout converted from the :cppkokkos:class:`View`'s *natural mdspan*.

.. cppkokkos:function:: template <class OtherAccessorType = Kokkos::default_accessor<typename traits::value_type>> constexpr auto to_mdspan(const OtherAccessorType& other_accessor = OtherAccessorType{})

:tparam OtherAccessor: the target mdspan accessor

:constraints: :cpp:`typename OtherAccessorType::data_handle_type` must be assignable to :cpp:`value_type*`

:returns: :cpp:class:`View`\ 's :ref:`natural mdspan <api-view-natural-mdspans>`, but with an accessor policy constructed from :cpp:any:`other_accessor`
:returns: :cppkokkos:class:`View`\ 's :ref:`natural mdspan <api-view-natural-mdspans>`, but with an accessor policy constructed from :cpp:any:`other_accessor`


NonMember Functions
Expand Down Expand Up @@ -633,9 +636,9 @@ Natural mdspans
.. versionadded:: 4.4.0

C++23 introduces `mdspan <https://en.cppreference.com/w/cpp/container/mdspan>`_, a non-owning multidimensional array view.
:cpp:class:`View` is compatible with :cpp:`std::mdspan` and can be implicitly converted from and to valid mdspans.
:cppkokkos:class:`View` is compatible with :cpp:`std::mdspan` and can be implicitly converted from and to valid mdspans.
These conversion rules are dictated by the *natural mdspan* of a view.
For an mdspan :cpp:`m` of type :cpp:`M` that is the *natural mdspan* of a :cpp:class:`View` :cpp:`v` of type :cpp:`V`, the following properties hold:
For an mdspan :cpp:`m` of type :cpp:`M` that is the *natural mdspan* of a :cppkokkos:class:`View` :cpp:`v` of type :cpp:`V`, the following properties hold:

#. :cpp:`M::value_type` is :cpp:`V::value_type`
#. :cpp:`M::index_type` is :cpp:`std::size_t`.
Expand Down
Loading