Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-14360

Pin pybtex/sphinxcontrib-bibtex dependencies in documenteer 0.2.x & dev guide update

    Details

      Description

      The Dev Guide suggests we use the following:

      .. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib
         :encoding: latex+latin
         :style: lsst_aa
      

      However, when I tried this with a recent sphinxcontrib-bibtex, I get:

      /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:508: ERROR: Error in "bibliography" directive:
      invalid option value: (option: "encoding"; value: 'latex+latin')
      unknown encoding: "latex+latin".
       
      .. bibliography:: lsst-texmf/texmf/bibtex/bib/refs_ads.bib
         :style: lsst_aa
         :encoding: latex+latin
      

      I think this is due to changes upstream (I didn't track it down fully, but I note that both sphixcontrib-bibtex and pybtex have been making changes to the way they handle encodings in recent releases).

      Simply removing the :encoding: line works fine for me.

        Attachments

          Activity

          swinbank John Swinbank created issue -
          swinbank John Swinbank made changes -
          Field Original Value New Value
          Risk Score 0
          swinbank John Swinbank made changes -
          Assignee John Swinbank [ swinbank ] Jonathan Sick [ jsick ]
          Hide
          swinbank John Swinbank added a comment -

          (Assigning this to SQuaRE/Jonathan Sick; I'm obviously capable of simply removing the offending line from the Dev Guide, but I'm not sure if there's some subtlety than I'm missing.)

          Show
          swinbank John Swinbank added a comment - (Assigning this to SQuaRE/ Jonathan Sick ; I'm obviously capable of simply removing the offending line from the Dev Guide, but I'm not sure if there's some subtlety than I'm missing.)
          swinbank John Swinbank made changes -
          Team SQuaRE [ 10302 ]
          swinbank John Swinbank made changes -
          Description The Dev Guide suggests we use the following:

          {code}
          .. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib
             :encoding: latex+latin
             :style: lsst_aa
          {code}

          However, when I tried this with a recent sphinxcontrib-bibtex, I get:

          {code}
          Users/jds/Projects/LSST/docs/dmtn/031/index.rst:508: ERROR: Error in "bibliography" directive:
          invalid option value: (option: "encoding"; value: 'latex+latin')
          unknown encoding: "latex+latin".

          .. bibliography:: lsst-texmf/texmf/bibtex/bib/refs_ads.bib
             :style: lsst_aa
             :encoding: latex+latin
          {code}

          I think this is due to changes upstream (I didn't track it down fully, but I note that both sphixcontrib-bibtex and pybtex have been making changes to the way they handle encodings in recent releases).

          Simply removing the {{:encoding:}} line works fine for me.
          The Dev Guide suggests we use the following:

          {code}
          .. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib
             :encoding: latex+latin
             :style: lsst_aa
          {code}

          However, when I tried this with a recent sphinxcontrib-bibtex, I get:

          {code}
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:508: ERROR: Error in "bibliography" directive:
          invalid option value: (option: "encoding"; value: 'latex+latin')
          unknown encoding: "latex+latin".

          .. bibliography:: lsst-texmf/texmf/bibtex/bib/refs_ads.bib
             :style: lsst_aa
             :encoding: latex+latin
          {code}

          I think this is due to changes upstream (I didn't track it down fully, but I note that both sphixcontrib-bibtex and pybtex have been making changes to the way they handle encodings in recent releases).

          Simply removing the {{:encoding:}} line works fine for me.
          Hide
          jsick Jonathan Sick added a comment -

          Interesting. On first look, the encoding parameter hasn't gone away (http://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#directive-bibliography) and its still in the current code. I'll need to solve this by pinning dependencies in the documenteer 0.2.x stream so that existing technotes don't break.

          Show
          jsick Jonathan Sick added a comment - Interesting. On first look, the encoding parameter hasn't gone away ( http://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#directive-bibliography)  and its still in the current code. I'll need to solve this by pinning dependencies in the documenteer 0.2.x stream so that existing technotes don't break.
          jsick Jonathan Sick made changes -
          Summary Developer Guide gives outdated advice about BibTeX encoding for ReST Pin pybtex/sphinxcontrib-bibtex dependencies in documenteer 0.2.x & dev guide update
          Hide
          swinbank John Swinbank added a comment -

          It definitely hasn't gone away — but it now seems to want just the character encoding of the source file, rather than the latex prefix. On my system, for example, :encoding: utf-8 works fine.

          Show
          swinbank John Swinbank added a comment - It definitely hasn't gone away — but it now seems to want just the character encoding of the source file, rather than the latex prefix. On my system, for example, :encoding: utf-8 works fine.
          Hide
          jsick Jonathan Sick added a comment -

          John Swinbank, I can't reproduce this bug report locally.

          Could you send:

          • pip freeze with your Python environment.
          • The exact git repo + git commit where I should see this error.

          The meaning of latex+latin is to indicate that non-ascii characters are encoded as LaTeX entities, not as unicode characters.

          Show
          jsick Jonathan Sick added a comment - John Swinbank , I can't reproduce this bug report locally. Could you send: pip freeze with your Python environment. The exact git repo + git commit where I should see this error. The meaning of latex+latin is to indicate that non-ascii characters are encoded as LaTeX entities, not as unicode characters.
          jsick Jonathan Sick made changes -
          Status To Do [ 10001 ] In Progress [ 3 ]
          jsick Jonathan Sick made changes -
          Story Points 0.2
          jsick Jonathan Sick made changes -
          Epic Link DM-13773 [ 39319 ]
          jsick Jonathan Sick made changes -
          Component/s Stack Documentation and UX [ 12880 ]
          Labels documenteer technote-platform
          swinbank John Swinbank made changes -
          Attachment swinbank-environment.txt [ 32803 ]
          Hide
          swinbank John Swinbank added a comment -

          Environment attached to the this ticket.

          I can reproduce the problem using this commit to DMTN-031 together with the following patch:

          diff --git a/index.rst b/index.rst
          index e3285c9..1d8c156 100644
          --- a/index.rst
          +++ b/index.rst
          @@ -651,5 +651,5 @@ comparison between the two algorithms and codes, we conclude that one could swit
           LSST Stack to PPMb without any notable drawbacks.
           
           .. bibliography:: lsst-texmf/texmf/bibtex/bib/refs_ads.bib
          -   :encoding: utf-8
          +   :encoding: latex+latin
              :style: lsst_aa
          

          This results in:

          $ make html
          sphinx-build -b html -d _build/doctrees  -n . _build/html
          Running Sphinx v1.5.6
          making output directory...
          loading pickled environment... not yet created
          building [mo]: targets for 0 po files that are out of date
          building [html]: targets for 1 source files that are out of date
          updating environment: 1 added, 0 changed, 0 removed
          reading sources... [100%] index
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:653: ERROR: Error in "bibliography" directive:
          invalid option value: (option: "encoding"; value: 'latex+latin')
          unknown encoding: "latex+latin".
           
          .. bibliography:: lsst-texmf/texmf/bibtex/bib/refs_ads.bib
             :encoding: latex+latin
             :style: lsst_aa
          looking for now-outdated files... none found
          pickling environment... done
          checking consistency... done
          preparing documents... done
          writing output... [100%] index
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:5: WARNING: citation not found: 2007PASA...24..189T
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:5: WARNING: citation not found: 2007PASA...24..189T
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:21: WARNING: citation not found: 2007PASA...24..189T
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:30: WARNING: citation not found: 2007PASA...24..189T
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:346: WARNING: citation not found: 2016ApJ...832..155F                                                                                                     
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:370: WARNING: citation not found: 2016A&A...595A...2G                                                                                                     
          /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:642: WARNING: citation not found: 2007PASA...24..189T                                                                                                     
          generating indices...
          writing additional pages... search
          copying static files... done
          copying extra files... done
          dumping search index in English (code: en) ... done
          dumping object inventory... done
          build succeeded, 8 warnings.
           
          Build finished. The HTML pages are in _build/html.
          

          Show
          swinbank John Swinbank added a comment - Environment attached to the this ticket. I can reproduce the problem using this commit to DMTN-031 together with the following patch: diff --git a/index.rst b/index.rst index e3285c9..1d8c156 100644 --- a/index.rst +++ b/index.rst @@ -651,5 +651,5 @@ comparison between the two algorithms and codes, we conclude that one could swit LSST Stack to PPMb without any notable drawbacks.   .. bibliography:: lsst-texmf/texmf/bibtex/bib/refs_ads.bib - :encoding: utf-8 + :encoding: latex+latin :style: lsst_aa This results in: $ make html sphinx-build -b html -d _build/doctrees -n . _build/html Running Sphinx v1.5.6 making output directory... loading pickled environment... not yet created building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:653: ERROR: Error in "bibliography" directive: invalid option value: (option: "encoding"; value: 'latex+latin') unknown encoding: "latex+latin".   .. bibliography:: lsst-texmf/texmf/bibtex/bib/refs_ads.bib :encoding: latex+latin :style: lsst_aa looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:5: WARNING: citation not found: 2007PASA...24..189T /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:5: WARNING: citation not found: 2007PASA...24..189T /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:21: WARNING: citation not found: 2007PASA...24..189T /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:30: WARNING: citation not found: 2007PASA...24..189T /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:346: WARNING: citation not found: 2016ApJ...832..155F /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:370: WARNING: citation not found: 2016A&A...595A...2G /Users/jds/Projects/LSST/docs/dmtn/031/index.rst:642: WARNING: citation not found: 2007PASA...24..189T generating indices... writing additional pages... search copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded, 8 warnings.   Build finished. The HTML pages are in _build/html.
          jsick Jonathan Sick made changes -
          Epic Link DM-13773 [ 39319 ] DM-5644 [ 23494 ]
          Hide
          swinbank John Swinbank added a comment -

          Note that this is now happening on Travis: see e.g. DMTN-093 build #20 and DM-15680:

          /home/[secure]/build/lsst-dm/dmtn-093/index.rst:482: ERROR: Error in "bibliography" directive:
          invalid option value: (option: "encoding"; value: 'latex+latin')
          unknown encoding: "latex+latin".
          .. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib
              :encoding: latex+latin
              :style: lsst_aa
          looking for now-outdated files... none found
          

          Show
          swinbank John Swinbank added a comment - Note that this is now happening on Travis: see e.g. DMTN-093 build #20 and DM-15680 : /home/[secure]/build/lsst-dm/dmtn-093/index.rst:482: ERROR: Error in "bibliography" directive: invalid option value: (option: "encoding"; value: 'latex+latin') unknown encoding: "latex+latin". .. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib :encoding: latex+latin :style: lsst_aa looking for now-outdated files... none found
          Hide
          jsick Jonathan Sick added a comment -

          Affirmative, will implement the fixes.

          Show
          jsick Jonathan Sick added a comment - Affirmative, will implement the fixes.
          jsick Jonathan Sick made changes -
          Epic Link DM-5644 [ 23494 ] DM-15819 [ 208467 ]
          jsick Jonathan Sick made changes -
          Story Points 0.2 0.5
          Hide
          jsick Jonathan Sick added a comment -

          Updated template in lsst-technote-bootstrap and related documentation in https://developer.lsst.io/project-docs/technotes.html#using-bibliographies-in-restructuredtext-technotes

          Show
          jsick Jonathan Sick added a comment - Updated template in lsst-technote-bootstrap and related documentation in https://developer.lsst.io/project-docs/technotes.html#using-bibliographies-in-restructuredtext-technotes
          jsick Jonathan Sick made changes -
          Resolution Done [ 10000 ]
          Status In Progress [ 3 ] Done [ 10002 ]

            People

            • Assignee:
              jsick Jonathan Sick
              Reporter:
              swinbank John Swinbank
              Watchers:
              John Swinbank, Jonathan Sick
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Summary Panel