Giter VIP home page Giter VIP logo

docs4nist's Introduction

Docs4NIST Action

This is a GitHub action that uses sphinx to build documentation and then host on https://pages.nist.gov as an approximation of ReadTheDocs.

Usage

Note: GitHub Actions' YAML implementation does not support list or array elements, so use a multiline string to declare formats, as illustrated above.

The self-generated documentation for this action is available at https://pages.nist.gov/Docs4NIST.

docs4nist's People

Contributors

guyer avatar

Stargazers

 avatar  avatar

Watchers

 avatar  avatar

Forkers

lgc33 ianhbell

docs4nist's Issues

Add pre-borg step

As noted by @ianhbell via email: "It would be nice to have the chance to do some things pre-borging, for instance running doxygen and executing notebooks after borging is much more complicated with the fact that the doc folder has moved during borging and the hard-coded paths all need to be fixed up throughout my scripts and config files. It would be nice if this could run after the conda environment is loaded."

Borging fails on themes with custom CSS

When I try to run the action against a repo set to use rtd_sphinx_theme or another theme with custom CSS like piccolo_theme, the browser looks for /_static/css/rtd_sphinx_theme.css or /_static/css/piccolo_theme.css rather than what those packages actually call the file, iirc theme.css. Using alabaster works fine, likely because it doesn't have custom css to link in.

Allow user to specify complete build environment

As requested by @ianhbell via email: "Do you think it would be possible to allow the user to specify the entire environment.yml, rather than interleaving the base one with the user-specified one? My current problem is a conflict between sphinx=7.1.2, which does not compile my pdf properly, and sphinx=7.2.6, which does compile, but which conflicts with some package, though I don’t know which one. I am able to build the docs with just my environment on my local machine with python=3.10 so it is something about the combination that is the problem. The conda file in the docker gives python=3.11 and I need python=3.10 to get everybody to play nicely together."

PDF upload looks for wrong file name?

As noted by @ianhbell via email: "The upload of PDF output for some reason is incorrectly looking for files like latex/teqp-docs.pdf but the action seems to be looking correctly for latex/teqp.pdf: https://github.com/usnistgov/NISTtheDocs2Death/blob/a8ee6b552afc67d4894218e5577e5d3237cf98a6/action.yml#L177-L179 . As a result, no latex/PDF output gets uploaded. I have no idea why this is happening as the NTD2D action seems correct and I think the PDF is getting generated properly, but there is zero shell output from the PDF build step so ???"

Should use xelatex instead of pdflatex

I am not sure where this happens, but you have unicode in your generated rst, it will fail to compile to PDF, you need to use instead xelatex which handles unicode usually flawlessly.

pre-build step not working correctly

As reported by @ianhbell via email: "There is something wrong in @main with pre-build. The pre-build seems to be interpreted in a different way than before, and it doesn’t find python to run my pre-build script. I thought maybe it was the multi-line pre-build script you helped me set up before, so I tried to pull it all into a single python script, but that doesn’t fix it either, it can’t find python. Perhaps it is how subprocess is being used to call the pre-build command. See: https://github.com/ianhbell/teqp-docs/actions/runs/6331159254/job/17195114598"

This happened after intentionally removing shell=True. Maybe interpretation of multi-line YAML strings is different?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.