Re: Sphinx Github actions problem

["Yendell, Gary \(DLSLtd, RAL, LSCI\) via Tech-talk" <tech-talk at aps.anl.gov>]

Hi Mark,

It looks like sphinx-notes/pages is doing what the peaceiris/actions-gh-pages [1] action does, with addition of running the sphinx build for you, but without actually deploying the branch it updates so that you have to do it manually. The latter is much more widely used.

I have a similar build of a project [2] using doxygen and sphinx that just runs `doxygen` and `sphinx-build -ET docs/ build/html/` directly and then uses the action like so:

      - name: Publish Docs

        if: github.event_name == 'push'

        # We pin to the SHA, not the tag, for security reasons.

        # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions

        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0

        with:

          github_token: ${{ secrets.GITHUB_TOKEN }}

          publish_dir: build/html/

          keep_files: true

to deploy the build directory to GitHub Pages. It works pretty nicely.

[1] https://github.com/peaceiris/actions-gh-pages

[2] https://github.com/dls-controls/pmacFilterControl/blob/main/.github/workflows/docs.yml

Cheers,

Gary

---

From: Tech-talk <tech-talk-bounces at aps.anl.gov> on behalf of Mark Rivers via Tech-talk <tech-talk at aps.anl.gov>
Sent: 09 March 2023 00:30
To: tech-talk at aps.anl.gov <tech-talk at aps.anl.gov>
Subject: RE: Sphinx Github actions problem

 

Folks,

 

I found a rather ugly solution.

 

• I had Doxygen put its output in docs/doxygenHTML
• I added these 2 lines to docs/source/conf.py

 

html_extra_path = ['../doxygenHTML']

exclude_patterns = ['index.html']

 

The first line tells Sphinx to copy all of the files in doxygenHTML/ to _build/html when it builds.  There seems to be no way to tell Sphinx to put the files in a subfolder, so there will be a conflict with index.html, which exists both for the Sphinx build and for the Doxygen build.  So the second line tells Sphinx to exclude copying the Doxygen index.html file.  In this specific case that is OK, because I had no useful information on the main Doxygen page, but in general this would be a serious issue.

 

I also had to add these lines to my Github Actions publish-docs.yml file after the Doxygen build:

 

    - name: Change Doxygen output permissions so Sphinx can delete

      run: |

        sudo chmod -R 777 docs/doxygenHTML

 

That is because Doxygen creates files owned by root, and Sphinx cannot delete them without changing their permissions.

 

It seems like there should be a better way to do this, so I am happy to hear any suggestions!

 

Thanks,

Mark

 

 

 

 

 

 

From: Mark Rivers
Sent: Wednesday, March 8, 2023 4:30 PM
To: tech-talk at aps.anl.gov
Cc: Jemian, Pete R. <jemian at anl.gov>
Subject: Sphinx Github actions problem

 

Folks,

 

I am trying to build the asyn Web pages with Github Actions.  I need to do 2 things:

• Run doxygen to build the source code documentation
• Run Sphinx to build the human-generated documentation

 

Both of these work separately, but not together.  If I run the Doxygen build first, it generates the output files fine.  But then the Sphinx build (sphinx-notes/pages@v2) tries to delete all of the files that Doxygen generated.  I have tried having the Doxygen output go into the following locations:

 

/docs/doxygenOutput

/doxygenOutput

/docs/source/_static/doxygenOutput

 

In all cases Doxygen works fine, but then the Sphinx build tries to delete the Doxygen files.  The Sphinx build the actually fails because the doxygen generated files are owned by root. But even if it succeeded it would not work, since those files need to remain after the build.

 

If I run the Sphinx build first then Doxygen fails because the Sphinx build has already deleted the docs/ directory containing the Doxyfile.

 

Any idea solve this?

 

Thanks,

Mark

 

 

-- 

This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail.
Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd.
Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message.
Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom