Experimental Physics and
Industrial Control System

From: Yendell, Gary (DLSLtd,RAL,LSCI) <gary.yendell at diamond.ac.uk>
Sent: Thursday, March 9, 2023 4:31 AM
To: tech-talk at aps.anl.gov; Mark Rivers <rivers at cars.uchicago.edu>
Subject: Re: Sphinx Github actions problem

 

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:

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

 

 

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

 

 

 

 

 

 

 

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