Content Comparison

...

The sphinxcontrib-confluencebuilder attempts to generate Confluence content but suffers from several shortcomings:. An example of hosting this document demonstrates the problems.

1. Several common code languages are not recognized, yielding these errors:

   Code Block
   language python linenumbers false
   WARNING: unknown code language: console WARNING: unknown code language: ini WARNING: unknown code language: json WARNING: unknown code language: text WARNING: unknown code language: tsql WARNING: unknown code language: yaml

   Some of these can be easily worked-around (e.g. substitute sql for tsql) but lack of text is pretty basic stuff.

2. Certain instances of curly braces are not properly quoted, leading to 500 macro unknown errors like this:

   Code Block
   language python linenumbers false
   An unsupported Confluence API call has been made. REQ: POST RSP: 500 URL: https://confluence.columbia.edu/confluence/rest/api API: contentbody/convert/storage MSG: com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'json' is unknown. ---

   Curly braces appear to be OK for normal body text but break down in:

   • browser link titles such as [See {json:api}](https://jsonapi.org)

   • autodoc-generated code blocks:

     Code Block
     language diff linenumbers false
     diff --git a/myapp/serializers.py b/myapp/serializers.py index beb962c..e8e15ac 100644 --- a/myapp/serializers.py +++ b/myapp/serializers.py @@ -70,8 +70,8 @@ class CourseSerializer(HyperlinkedModelSerializer): related_link_view_name='course-related', ) - #: `{json:api} compound document <https://jsonapi.org/format/#document-compound-documents>`_ - #: (also used for `related_serializers` for DJA 2.6.0) + # `JSON:API compound document <https://jsonapi.org/format/#document-compound-documents>`_ + # (also used for `related_serializers` for DJA 2.6.0) included_serializers = { 'course_terms': 'myapp.serializers.CourseTermSerializer', } @@ -111,8 +111,8 @@ class CourseTermSerializer(HyperlinkedModelSerializer): related_link_view_name='course_term-related', )

     These can be worked around by excluding undocumented members and removing docstrings or #: comments (which sphinx treats like docstrings). This was supposedly fixed but is apparently not (or this is a new way to trigger the issue). A fix is in the works.

3. There’s no way to put the ToC in the sidebar so navigation sucks.

4. No search.

5. Poor formatting of autodocs.

...