Merge pull request #117 from PJK/pk/fix-man

Documentation fixes
PJK · Mar 15, 2020 · c546dbe · c546dbe
2 parents 2b842d9 + 6a4d069
commit c546dbe
Show file tree

Hide file tree

Showing 6 changed files with 21 additions and 20 deletions.
diff --git a/doc/source/api/item_reference_counting.rst b/doc/source/api/item_reference_counting.rst
@@ -10,7 +10,7 @@ Using custom allocator
 
 *libcbor* gives you with the ability to provide your own implementations of ``malloc``, ``realloc``, and ``free``. This can be useful if you are using a custom allocator throughout your application, or if you want to implement custom policies (e.g. tighter restrictions on the amount of allocated memory).
 
-In order to use this feature, *libcbor* has to be compiled with the :doc:`appropriate flags <getting_started>`. You can verify the configuration using the ``CBOR_CUSTOM_ALLOC`` macro. A simple usage might be as follows:
+In order to use this feature, *libcbor* has to be compiled with the :doc:`appropriate flags </getting_started>`. You can verify the configuration using the ``CBOR_CUSTOM_ALLOC`` macro. A simple usage might be as follows:
 
 .. code-block:: c
 

diff --git a/doc/source/api/type_0_1.rst b/doc/source/api/type_0_1.rst
@@ -30,7 +30,7 @@ Type 0 & 1
 -------------
 Due to their largely similar semantics, the following functions can be used for both Type 0 and Type 1 items. One can convert between them freely using `the conversion functions <#dealing-with-signedness>`_.
 
-Actual Type of the integer can be checked using :ref:`item types API <item-types>`.
+Actual Type of the integer can be checked using :doc:`item types API <item_types>`.
 
 
 

diff --git a/doc/source/api/type_7.rst b/doc/source/api/type_7.rst
@@ -65,8 +65,7 @@ Manipulating existing items
 Half floats
 ~~~~~~~~~~~~
 CBOR supports two `bytes wide ("half-precision") <https://en.wikipedia.org/wiki/Half-precision_floating-point_format>`_
-floats which are not supported by the C language. *libcbor* represents them using :type:`float`
-values throughout the API, which has important implications when manipulating these values.
+floats which are not supported by the C language. *libcbor* represents them using `float <https://en.cppreference.com/w/c/language/type>` values throughout the API, which has important implications when manipulating these values.
 
 In particular, if a user uses some of the manipulation APIs
 (e.g. :func:`cbor_set_float2`, :func:`cbor_new_float2`)

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -42,11 +42,11 @@
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 if on_rtd:
-    print subprocess.check_output('cd ../..; mkdir doc/build; doxygen', shell=True)
+    print(subprocess.check_output('cd ../..; mkdir doc/build; doxygen', shell=True))
 
 
-print os.getcwd()
-print os.getcwd() + '/../build/doxygen/xml'
+print(os.getcwd())
+print(os.getcwd() + '/../build/doxygen/xml')
 
 breathe_projects = {
     'libcbor': '../build/doxygen/xml'
@@ -67,8 +67,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'libcbor'
-copyright = u'2014 - 2019, Pavel Kalvoda'
+project = 'libcbor'
+copyright = '2014 - 2019, Pavel Kalvoda'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -156,7 +156,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -225,8 +225,8 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', 'libcbor.tex', u'libcbor Documentation',
-   u'Pavel Kalvoda', 'manual'),
+  ('index', 'libcbor.tex', 'libcbor Documentation',
+   'Pavel Kalvoda', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -255,8 +255,8 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'libcbor', u'libcbor Documentation',
-     [u'Pavel Kalvoda'], 1)
+    ('index', 'libcbor', 'libcbor Documentation',
+     ['Pavel Kalvoda'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -269,8 +269,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'libcbor', u'libcbor Documentation',
-   u'Pavel Kalvoda', 'libcbor', 'C library for parsing and generating CBOR.',
+  ('index', 'libcbor', 'libcbor Documentation',
+   'Pavel Kalvoda', 'libcbor', 'C library for parsing and generating CBOR.',
    'Miscellaneous'),
 ]
 

diff --git a/doc/source/internal.rst b/doc/source/internal.rst
@@ -62,7 +62,7 @@ Generally speaking, data items consist of three parts:
 
  - a generic :type:`handle <cbor_item_t>`,
  - the associated :type:`metadata <cbor_item_metadata>`,
- - and the :type:`actual data  <cbor_item_t.data>`
+ - and the actual data
 
 .. type:: cbor_item_t
 
@@ -78,7 +78,7 @@ Generally speaking, data items consist of three parts:
 
     .. member:: union cbor_item_metadata metadata
 
-        Union discriminated by :member:`cbor_item_t.type`. Contains type-specific metadata
+        Union discriminated by :member:`type`. Contains type-specific metadata
 
     .. member:: unsigned char * data
 
@@ -106,7 +106,9 @@ Generally speaking, data items consist of three parts:
         Dynamically sized types (:doc:`api/type_2`, :doc:`api/type_3`, :doc:`api/type_4`, :doc:`api/type_5`) may store handle and data in separate locations. This enables creating large items (e.g :doc:`byte strings <api/type_2>`) without :func:`realloc` or copying large blocks of memory. One simply attaches the correct pointer to the handle.
 
 
-.. type:: union cbor_item_metadata
+.. type:: cbor_item_metadata
+
+    Union type of the following members, based on the item type:
 
     .. member:: struct _cbor_int_metadata int_metadata;
 

diff --git a/doc/source/rfc_conformance.rst b/doc/source/rfc_conformance.rst
@@ -11,7 +11,7 @@ There is no explicit limitation of indefinite length byte strings. [#]_ *libcbor
 
 "Half-precision" IEEE 754 floats
 ---------------------------------
-As of C99 and even C11, there is no standard implementation for 2 bytes floats. *libcbor* packs them as a :type:`float`. When encoding, *libcbor* selects the appropriate wire representation based on metadata and the actual value. This applies both to canonical and normal mode.
+As of C99 and even C11, there is no standard implementation for 2 bytes floats. *libcbor* packs them as a `float <https://en.cppreference.com/w/c/language/type>`. When encoding, *libcbor* selects the appropriate wire representation based on metadata and the actual value. This applies both to canonical and normal mode.
 
 For more information on half-float serialization, please refer to the section on :ref:`api_type_7_hard_floats`.
-Original file line number
+Diff line change
@@ Expand Up / @@ -30,7 +30,7 @@ Type 0 & 1 @@
     -------------
     Due to their largely similar semantics, the following functions can be used for both Type 0 and Type 1 items. One can convert between them freely using `the conversion functions <#dealing-with-signedness>`_.
-    Actual Type of the integer can be checked using :ref:`item types API <item-types>`.
+    Actual Type of the integer can be checked using :doc:`item types API <item_types>`.
@@ Expand Down @@