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

WARNING: Misc sphinx-guides formatting clean up #6997

Closed
mheppler opened this issue Jun 17, 2020 · 2 comments · Fixed by #6998
Closed

WARNING: Misc sphinx-guides formatting clean up #6997

mheppler opened this issue Jun 17, 2020 · 2 comments · Fixed by #6998
Labels
Feature: Admin Guide Feature: API Guide Feature: Developer Guide Feature: Installation Guide

Comments

@mheppler
Copy link
Contributor

mheppler commented Jun 17, 2020 •
edited

Thank you to @landreev for identifying this issue. Built the latest guides from develop and Sphinx was not a happy camper. Dumping all warnings here. PR to follow.

sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.8.2
making output directory...
                                                                                                                              
/dataverse/doc/sphinx-guides/source/developers/deployment.rst:87: WARNING: Mismatch: both interpreted text role prefix and reference suffix.
/dataverse/doc/sphinx-guides/source/developers/testing.rst:3: WARNING: Duplicate explicit target name: "testcontainers".
/dataverse/doc/sphinx-guides/source/developers/testing.rst:140: WARNING: Unknown target name: "dataverse-ansible repo<https://github.com/iqss/dataverse-ansible/>".
/dataverse/doc/sphinx-guides/source/developers/testing.rst:142: WARNING: Unknown target name: "ec2-create-instance.sh<https://raw.githubusercontent.com/iqss/dataverse-ansible/master/ec2/ec2-create-instance.sh>".
/dataverse/doc/sphinx-guides/source/developers/testing.rst:143: WARNING: Unknown target name: "main.yml<https://raw.githubusercontent.com/iqss/dataverse-ansible/master/defaults/main.yml>".
/dataverse/doc/sphinx-guides/source/installation/config.rst:253: WARNING: Title underline too short.

Multi-store Basics
+++++++++++++++++

/dataverse/doc/sphinx-guides/source/installation/config.rst:268: WARNING: Error in "code-block" directive:

1 argument(s) required, 0 supplied.

.. code-block::

        ./asadmin $ASADMIN_OPTS delete-jvm-options "-Ddataverse.files.storage-driver-id=file"
        ./asadmin $ASADMIN_OPTS create-jvm-options "-Ddataverse.files.storage-driver-id=<id>"

/dataverse/doc/sphinx-guides/source/installation/config.rst:537: WARNING: Malformed table.

Text in column margin in table line 9.

=========================================    ==================  ==================================================================  =============
JVM Option                                   Value               Description                                                         Default value
=========================================    ==================  ==================================================================  =============
dataverse.files.storage-driver-id            <id>                Enable <id> as the default storage driver.                          ``file``
dataverse.files.<id>.bucket-name             <?>                 The bucket name. See above.                                         (none)
dataverse.files.<id>.download-redirect       ``true``/``false``  Enable direct download or proxy through Dataverse.                  ``false``
dataverse.files.<id>.upload-redirect         ``true``/``false``  Enable direct upload of files added to a dataset  to the S3 store.  ``false``
dataverse.files.<id>.ingestsizelimit         <size in bytes>     Maximum size of directupload files that should be ingested          (none)
dataverse.files.<id>.url-expiration-minutes  <?>                 If direct uploads/downloads: time until links expire. Optional.     60
dataverse.files.<id>.custom-endpoint-url     <?>                 Use custom S3 endpoint. Needs URL either with or without protocol.  (none)
dataverse.files.<id>.custom-endpoint-region  <?>                 Only used when using custom endpoint. Optional.                     ``dataverse``
dataverse.files.<id>.path-style-access       ``true``/``false``  Use path style buckets instead of subdomains. Optional.             ``false``
dataverse.files.<id>.payload-signing         ``true``/``false``  Enable payload signing. Optional                                    ``false``
dataverse.files.<id>.chunked-encoding        ``true``/``false``  Disable chunked encoding. Optional                                  ``true``
=========================================    ==================  ==================================================================  =============

/dataverse/doc/sphinx-guides/source/installation/config.rst:1071: WARNING: malformed hyperlink target.
                                                                                                                                   
/dataverse/doc/sphinx-guides/source/admin/troubleshooting.rst:23: WARNING: unknown document: config
/dataverse/doc/sphinx-guides/source/api/apps.rst:4: WARNING: unknown document: /admin/reporting-tools
/dataverse/doc/sphinx-guides/source/installation/config.rst:262: WARNING: unknown document: dataverses-datasets
/dataverse/doc/sphinx-guides/source/installation/config.rst:273: WARNING: undefined label: :maxfileuploadsizeinbytes (if the link has no caption the label must precede a section header)
/dataverse/doc/sphinx-guides/source/installation/config.rst:1568: WARNING: unknown document: /admin/reporting-tools
@mheppler
Copy link
Contributor Author

For future reference, formatting documentation for Sphinx can be found at https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.

Sections

Section headers (ref) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

=================
This is a heading

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python’s Style Guide for documenting which you may follow:

# with overline, for parts

* with overline, for chapters

=, for sections

-, for subsections

^, for subsubsections

", for paragraphs

Of course, you are free to use your own marker characters (see the reST documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth.

@mheppler
Copy link
Contributor Author

mheppler commented Jun 17, 2020 •
edited

/developers/deployment.rst

  • line 87: Mismatch: both interpreted text role prefix and reference suffix, needed to remove the :download: prefix since it is not a local file, treating it as a normal link now

/developers/testing.rst

  • line 3: duplicate target name, needed double underscore
  • line 140: Unknown target name, needed space between link text and url bracket
  • line 142: Unknown target name, needed space between link text and url bracket
  • line 143: Unknown target name, needed space between link text and url bracket

/installation/config.rst

  • line 253: Title underline too short, needed one more +
  • line 262: unknown document, needed /admin/ added to dataverses-datasets link
  • line 268: Error in "code-block" directive, need to set the code-block language to none as that value is required (which was later changed to optional in Sphinx 2.0)
  • line 273: undefined label, needed .. _:MaxFileUploadSizeInBytes: section target
  • line 537: Malformed table. Text in column margin in table line 9, needed additional = for JVM Option column to equal the length of the longest column content
  • line 1071: malformed hyperlink target, needed : after section target
  • line 1568: unknown document, needed -and-queries added to reporting-tools link

/admin/troubleshooting.rst

  • line 23: unknown document, needed /installation/ added to config link

/api/apps.rst

  • line 4: unknown document, needed -and-queries added to reporting-tools link

mheppler added a commit that referenced this issue Jun 17, 2020
@mheppler
Cleaned up format warnings when building sphinx-guides [ref #6997]
61bfb4e
@mheppler mheppler mentioned this issue Jun 17, 2020
Merged
pdurbin added a commit that referenced this issue Jun 22, 2020
@pdurbin
fix "WARNING: download file not readable" #6997
c3b5982
pdurbin added a commit that referenced this issue Jun 22, 2020
@pdurbin
fix formatting around solr #6997
23a5827
pdurbin added a commit that referenced this issue Jun 22, 2020
@pdurbin
fix formating around minio, s3 #6997
c8a2302
kcondon added a commit that referenced this issue Jul 1, 2020
@kcondon
Merge pull request #6998 from IQSS/6997-guides-clean-up
4eda5a1 
Cleaned up format warnings when building sphinx-guides [ref #6997]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Feature: Admin Guide Feature: API Guide Feature: Developer Guide Feature: Installation Guide
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Cleaned up format warnings when building sphinx-guides [ref #6997] IQSS/dataverse
1 participant
@mheppler