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

Support sphinxcontrib-bibtex in technotes

    XMLWordPrintable

    Details

      Description

      Allow bibtex-based references in technotes using sphinxcontrib-bibtex. Includes:

      • Changes to documenteer Sphinx configuration for technotes.
      • Addition of bibliography in technote boilerplate.
      • Documentation of our requirements to use bibtex for different types of references.

      DMTN-010 will be used as a pilot case.

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            I agree with the need to use ADS entries verbatim.

            It looks like the pybtex folks plane sphinxcontrib-bibtex for this (https://bitbucket.org/pybtex-devs/pybtex/issues/65/percent-sign-in-url-field-raises-an) and sphinxcontrib-bibtex points to latexcodec (http://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#encoding-percent-signs). Maybe we can PR a fix to latexdoc?

            The immediate ways forward for this ticket at are:

            1. Accept manual patches to the bibtex to escape %, or
            2. Don't automatically populate lsst-bibtex bibliographies in Sphinx technotes and instead recommend that bibliographies be curated separately in each technote.

            I'm hoping to do 1, but will be happy to do 2 to ship this ticket.

            Show
            jsick Jonathan Sick added a comment - I agree with the need to use ADS entries verbatim. It looks like the pybtex folks plane sphinxcontrib-bibtex for this ( https://bitbucket.org/pybtex-devs/pybtex/issues/65/percent-sign-in-url-field-raises-an ) and sphinxcontrib-bibtex points to latexcodec ( http://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#encoding-percent-signs ). Maybe we can PR a fix to latexdoc? The immediate ways forward for this ticket at are: 1. Accept manual patches to the bibtex to escape % , or 2. Don't automatically populate lsst-bibtex bibliographies in Sphinx technotes and instead recommend that bibliographies be curated separately in each technote. I'm hoping to do 1, but will be happy to do 2 to ship this ticket.
            Hide
            tjenness Tim Jenness added a comment -

            Option 1. is fine as a temporary fix if the URLs in PDFs still go to the right place. I think it has to be sphinxcontrib-bibtex that is fixed. URL fields in bib files should not be treated as latex at all. They have to be treated as valid URLs.

            Show
            tjenness Tim Jenness added a comment - Option 1. is fine as a temporary fix if the URLs in PDFs still go to the right place. I think it has to be sphinxcontrib-bibtex that is fixed. URL fields in bib files should not be treated as latex at all. They have to be treated as valid URLs.
            Hide
            jsick Jonathan Sick added a comment -

            These PRs are involved:

            1. https://github.com/lsst-sqre/lsst-technote-bootstrap/pull/12 (technote template additions)
            2. https://github.com/lsst-sqre/documenteer/pull/16 (Sphinx extension and bib management tool)
            3. https://github.com/lsst/lsst-texmf/pull/88 (sphinxcontrib-bibtex compatibility for common bib files)
            Show
            jsick Jonathan Sick added a comment - These PRs are involved: https://github.com/lsst-sqre/lsst-technote-bootstrap/pull/12 (technote template additions) https://github.com/lsst-sqre/documenteer/pull/16 (Sphinx extension and bib management tool) https://github.com/lsst/lsst-texmf/pull/88 (sphinxcontrib-bibtex compatibility for common bib files)
            Hide
            tjenness Tim Jenness added a comment -

            Looks okay for now. Comments on PR.

            Show
            tjenness Tim Jenness added a comment - Looks okay for now. Comments on PR.
            Hide
            jsick Jonathan Sick added a comment -

            Thanks for the astute comments Tim Jenness. I'll put out a community.lsst.org post outlining the new technote features (after I've upgraded technotes to use documenteer 0.2).

            Show
            jsick Jonathan Sick added a comment - Thanks for the astute comments Tim Jenness . I'll put out a community.lsst.org post outlining the new technote features (after I've upgraded technotes to use documenteer 0.2).

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              jsick Jonathan Sick
              Reviewers:
              Tim Jenness
              Watchers:
              John Parejko, Jonathan Sick, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.