No Build Action

[drfrpjr]

Hi,

This is in regard to the GitHub repo: https://github.com/usnistgov/WebFF-Documentation

I have added the Docs4NIST.yml file, edited the Sphinx build files to match the Docs4NIST requirements, and added a Webhook according to the instructions on this page:

https://github.com/usnistgov/pages-root/wiki/Configuring-your-repo-for-publishing-on-pages.nist.gov

I also did a push to try and trigger the build, but still no manual pages appear on pages.nist.gov, nor are there any email messages indicating that a build was attempted.

Then on further inspection I found that Actions permissions are disabled on this page with no possibility of changing the settings:

https://github.com/usnistgov/WebFF-Documentation/settings/actions

So, at this point I am not sure if I did something wrong or if the Actions settings are stopping any build from happening.

Any advice on this would be great.

Thanks, ~Fred

[guyer]

At https://pages.nist.gov/Docs4NIST/en/latest/index.html#usage, step 2 is

Enable GitHub Actions for your repo and select “Allow all actions and reusable workflows” (you may need to submit a request to devops@nist.gov to enable this for you).

[drfrpjr]

Thanks, I contacted them.

~Fred

Frederick R. Phelan Jr., Ph.D. Functional Polymers Group NIST/MML/MSED Gaithersburg, MD, 20899

Sent from Laptop

From: Jonathan Guyer @.> Sent: Wednesday, February 28, 2024 6:56 PM To: usnistgov/Docs4NIST @.> Cc: Phelan Jr., Frederick R. Dr. (Fed) @.>; Author @.> Subject: Re: [usnistgov/Docs4NIST] No Build Action (Issue #23)

At https://pages.nist.gov/Docs4NIST/en/latest/index.html#usage, step 2 is

Enable GitHub Actions for your repohttps://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository and select "Allow all actions and reusable workflows" (you may need to submit a request to @.***<mailto:devops%40nist.gov> to enable this for you).

- Reply to this email directly, view it on GitHubhttps://github.com/usnistgov/Docs4NIST/issues/23#issuecomment-1970124667, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADRCU3FUZSY6GCBK7KG4EJLYV67YLAVCNFSM6AAAAABD6XHFP6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNZQGEZDINRWG4. You are receiving this because you authored the thread.Message ID: @.**@.>>

[drfrpjr]

So, this now executes. I have cleaned up all the execution errors but one related to Node.j 16 actions vs. Node.js 20 actions. I have no idea on this.

Here is the output: https://github.com/usnistgov/WebFF-Documentation/actions/runs/8101231007

The error is:

docs Node.js 16 actions are deprecated. Please update the following actions to use Node.js 20: actions/checkout@v3, actions/upload-artifact@v3. For more information see: https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/.

Curiously, the link shows no actual error messages, just a bunch of Warnings. But, the web pages do not appear so something went wrong.

Also, one of the errors I eliminated was related to the header/footer insertion. Apparently, "include-header-footer" has been changed to "insert-header-footer". That will effect what is in the documentation.

[guyer]

The comment about Node.js is a warning not an error. I'll look into it.

The web pages do not appear because you do not have a nist-pages branch. This should have been done when Configuring your repo for publishing on pages.nist.gov.

Also, one of the errors I eliminated was related to the header/footer insertion. Apparently, "include-header-footer" has been changed to "insert-header-footer". That will effect what is in the documentation.

Thank you for pointing that out.

The significant error is here: https://github.com/usnistgov/WebFF-Documentation/actions/runs/8101231007/job/22140978971#step:2:811

Failed to import WebFF.

[drfrpjr]

In regard to the nist-pages branch, I thought that was optional and you could use master? That is what I set it to in the YML file. I'm a bit confused on this point.

In regard to the WebFF module import, I saw that but it shows as a WARNING so I did not think it pertinent ... but I do see the TabError thing now.

I guess you are saying because an exception is raised it is fatal?

I'll work on the tabs tomorrow.

@.***

Thanks for the feedback.

~Fred

Frederick R. Phelan Jr., Ph.D. Functional Polymers Group NIST/MML/MSED Gaithersburg, MD, 20899

Sent from Laptop

From: Jonathan Guyer @.> Sent: Thursday, February 29, 2024 9:46 PM To: usnistgov/Docs4NIST @.> Cc: Phelan Jr., Frederick R. Dr. (Fed) @.>; Author @.> Subject: Re: [usnistgov/Docs4NIST] No Build Action (Issue #23)

The comment about Node.js is a warning not an error. I'll look into it.

The web pages do not appear because you do not have a nist-pages branch. This should have been done when Configuring your repo for publishing on pages.nist.govhttps://github.com/usnistgov/pages-root/wiki/Configuring-your-repo-for-publishing-on-pages.nist.gov.

Also, one of the errors I eliminated was related to the header/footer insertion. Apparently, "include-header-footer" has been changed to "insert-header-footer". That will effect what is in the documentation.

Thank you for pointing that out.

The significant error is here: https://github.com/usnistgov/WebFF-Documentation/actions/runs/8101231007/job/22140978971#step:2:811

Failed to import WebFF.

- Reply to this email directly, view it on GitHubhttps://github.com/usnistgov/Docs4NIST/issues/23#issuecomment-1972366935, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADRCU3BPU5A75JUCKS4BTK3YV7TVFAVCNFSM6AAAAABD6XHFP6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNZSGM3DMOJTGU. You are receiving this because you authored the thread.Message ID: @.***>

[guyer]

A nist-pages branch is not optional. It's how pages.nist.gov works.

In regard to the WebFF module import, I saw that but it shows as a WARNING so I did not think it pertinent ... but I do see the TabError thing now.

Huh? The line I linked to starts with "Error:"

Sphinx wants to import your package in order to document it.

[drfrpjr]

OK, I clicked on that link you sent in the email it did not really go to a specific line. I'm in the Issues section in the browser now and I can see what you meant. I first saw line 682 which calls it a WARNING. But, I see there are two Errors, one on 797 and the other on 812.

It looks like the first at 797 is a theme error. Is 'sphinxdoc' not allowed as a theme?

To back up to the nist-pages thing, the idea is to jump back and forth between working on code in the master branch and the documentation pages in the nist-pages branch? Or just move it all to nist-pages? I'm a little traumatized by this but I'll figure out a way to work through it if everyone else is. What are best practices?

[guyer]

It looks like the first at 797 is a theme error. Is 'sphinxdoc' not allowed as a theme?

It's supposed to be, but I agree that it doesn't work. I know what's happening, but haven't figured out what to do about it. In the meantime, you should be able to use any of agogo, basic, bizstyle, classic, epub, haiku, nonav, pyramid, or scrolls.

To back up to the nist-pages thing, the idea is to jump back and forth between working on code in the master branch and the documentation pages in the nist-pages branch? Or just move it all to nist-pages? I'm a little traumatized by this but I'll figure out a way to work through it if everyone else is. What are best practices?

No. Just create a nist-pages branch. You do not need to do anything with it after that. The Docs4NIST action takes care of building your docs and putting the content on the nist-pages branch, where pages.nist.gov is looking for your webpage content.

[guyer]

It's supposed to be, but I agree that it doesn't work. I know what's happening, but haven't figured out what to do about it. In the meantime, you should be able to use any of agogo, basic, bizstyle, classic, epub, haiku, nonav, pyramid, or scrolls.

I've filed sphinx-doc/sphinx#12049. Still looking for a workaround.

[drfrpjr]

OK, thanks for the heads up. I've been tied up with APS. I'll get back to this tomorrow. I'm sure one of the other styles is acceptable.

~Fred

Frederick R. Phelan Jr., Ph.D. Functional Polymers Group NIST/MML/MSED Gaithersburg, MD, 20899

Sent from Laptop

From: Jonathan Guyer @.> Sent: Wednesday, March 6, 2024 8:29 AM To: usnistgov/Docs4NIST @.> Cc: Phelan Jr., Frederick R. Dr. (Fed) @.>; Author @.> Subject: Re: [usnistgov/Docs4NIST] No Build Action (Issue #23)

It's supposed to be, but I agree that it doesn't work. I know what's happening, but haven't figured out what to do about it. In the meantime, you should be able to use any of agogo, basic, bizstyle, classic, epub, haiku, nonav, pyramid, or scrolls.

I've filed sphinx-doc/sphinx#12049https://github.com/sphinx-doc/sphinx/issues/12049. Still looking for a workaround.

- Reply to this email directly, view it on GitHubhttps://github.com/usnistgov/Docs4NIST/issues/23#issuecomment-1980874567, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADRCU3BKP2TPTURWHRU2OR3YW4KZBAVCNFSM6AAAAABD6XHFP6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOBQHA3TINJWG4. You are receiving this because you authored the thread.Message ID: @.**@.>>

[guyer]

I've been able to figure out a fix, I think. Change your Docs4NIST.yml to

name: "Build WebFF Documentation"

on: [push, pull_request, delete]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: usnistgov/Docs4NIST@0.6
        with:
          docs-folder: Docs/manual/

[drfrpjr]

OK, are you saying to change that up but leave the html_theme as "sphinxdoc"? Just wanted to clarify.

Also, I'm still working on the tabs in the module which will take a few more hours. Unfortunately, this module was worked on by a number of student interns and that led to a mix of tabs and spaces that apparently the Docs4NIST system objects too. However, this same code unaltered worked fine on Read The Docs and also previous private Sphinx builds. I'll fix it to make it consistent but do you know if you have a particular switch set to enforce some kind of tabs/spaces policy? That would be good to know in advance.

I'll get back to you when I try the build.

Thanks,

~Fred

Frederick R. Phelan Jr., Ph.D. Functional Polymers Group NIST/MML/MSED Gaithersburg, MD, 20899

Sent from Telework WS

From: Jonathan Guyer @.> Sent: Wednesday, March 6, 2024 8:11 PM To: usnistgov/Docs4NIST @.> Cc: Phelan Jr., Frederick R. Dr. (Fed) @.>; Author @.> Subject: Re: [usnistgov/Docs4NIST] No Build Action (Issue #23)

I've been able to figure out a fix, I think. Change your Docs4NIST.ymlhttps://github.com/usnistgov/WebFF-Documentation/tree/master/.github/workflows/Docs4NIST.yml to

name: "Build WebFF Documentation"

on: [push, pull_request, delete]

jobs:

docs:

runs-on: ubuntu-latest

steps:

  - uses: ***@***.******@***.***>

    with:

      docs-folder: Docs/manual/

- Reply to this email directly, view it on GitHubhttps://github.com/usnistgov/Docs4NIST/issues/23#issuecomment-1982156682, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADRCU3H27ZV7N277427R6WTYW65BNAVCNFSM6AAAAABD6XHFP6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOBSGE2TMNRYGI. You are receiving this because you authored the thread.Message ID: @.**@.>>

[guyer]

OK, are you saying to change that up but leave the html_theme as "sphinxdoc"? Just wanted to clarify.

Yes, that's what I'm saying.

Also, I'm still working on the tabs in the module which will take a few more hours. Unfortunately, this module was worked on by a number of student interns and that led to a mix of tabs and spaces that apparently the Docs4NIST system objects too.

It's not Docs4NIST that objects. Mixed tabs and spaces have always been discouraged in Python. They have generated an error since Python 3 came out in 2008. Python 2.7 was declared end-of-life in 2020.

However, this same code unaltered worked fine on Read The Docs and also previous private Sphinx builds. I'll fix it to make it consistent but do you know if you have a particular switch set to enforce some kind of tabs/spaces policy? That would be good to know in advance.

https://webff-documentation.readthedocs.io/en/latest/ appears to be over five years old.

[drfrpjr]

I pushed the module first before changing from 0.5 to 0.6. It failed because it can't find and external module named 'xlrd'.

Why does it care about that?!

Also, after that I changed the yml file from 0.5 to 0.6. But, with change it does not even seem to run the build at all.

~Fred

Frederick R. Phelan Jr., Ph.D. Functional Polymers Group NIST/MML/MSED Gaithersburg, MD, 20899

Sent from Telework WS

From: Jonathan Guyer @.> Sent: Wednesday, March 6, 2024 8:11 PM To: usnistgov/Docs4NIST @.> Cc: Phelan Jr., Frederick R. Dr. (Fed) @.>; Author @.> Subject: Re: [usnistgov/Docs4NIST] No Build Action (Issue #23) Importance: High

I've been able to figure out a fix, I think. Change your Docs4NIST.ymlhttps://github.com/usnistgov/WebFF-Documentation/tree/master/.github/workflows/Docs4NIST.yml to

name: "Build WebFF Documentation"

on: [push, pull_request, delete]

jobs:

docs:

runs-on: ubuntu-latest

steps:

  - uses: ***@***.******@***.***>

    with:

      docs-folder: Docs/manual/

- Reply to this email directly, view it on GitHubhttps://github.com/usnistgov/Docs4NIST/issues/23#issuecomment-1982156682, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADRCU3H27ZV7N277427R6WTYW65BNAVCNFSM6AAAAABD6XHFP6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOBSGE2TMNRYGI. You are receiving this because you authored the thread.Message ID: @.**@.>>

[drfrpjr]

OK, never mind. I forgot about the orphan branch.

---

I pushed the module first before changing from 0.5 to 0.6. It failed because it can't find and external module named 'xlrd'.

Why does it care about that?!

Also, after that I changed the yml file from 0.5 to 0.6. But, with change it does not even seem to run the build at all.

~Fred

Frederick R. Phelan Jr., Ph.D. Functional Polymers Group NIST/MML/MSED Gaithersburg, MD, 20899

Sent from Telework WS

From: Jonathan Guyer @.> Sent: Wednesday, March 6, 2024 8:11 PM To: usnistgov/Docs4NIST @.> Cc: Phelan Jr., Frederick R. Dr. (Fed) @.>; Author @.> Subject: Re: [usnistgov/Docs4NIST] No Build Action (Issue #23) Importance: High

I've been able to figure out a fix, I think. Change your Docs4NIST.ymlhttps://github.com/usnistgov/WebFF-Documentation/tree/master/.github/workflows/Docs4NIST.yml to

name: "Build WebFF Documentation"

on: [push, pull_request, delete]

jobs:

docs:

runs-on: ubuntu-latest

steps:

  - uses: ***@***.******@***.***>

    with:

      docs-folder: Docs/manual/

- Reply to this email directly, view it on GitHubhttps://github.com/usnistgov/Docs4NIST/issues/23#issuecomment-1982156682, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADRCU3H27ZV7N277427R6WTYW65BNAVCNFSM6AAAAABD6XHFP6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOBSGE2TMNRYGI. You are receiving this because you authored the thread.Message ID: @.**@.>>

[drfrpjr]

Before I run this again, I need to understand why it fails because it can't find an external module named 'xlrd'.

Why does it care about external modules at all?

[drfrpjr]

Confirmed that a new build does not run with Docs4NIST@0.6 ... I switched back to 0.5 and it runs, albeit with errors. But, at least I can now debug other problems besides the external xlrd reference.

[guyer]

Before I run this again, I need to understand why it fails because it can't find an external module named 'xlrd'.

Why does it care about external modules at all?

Your Sphinx configuration uses autodoc (as well as autosummary and napoleon, which also invoke autodoc). As it says near the top of its documentation, "autodoc imports the modules to be documented", so it imports your package. Your package imports xlrd. Hence, in order to build your documentation, as you configured it, Sphinx needs xlrd.

[drfrpjr]

OK, how do I give Sphinx xlrd in your Docs4NIST Python environment?

I am not aware of any information on this topic on the Docs4NIST website.

Further, having done nothing to define the Python environment at all and it imports xml.etree.ElementTree without any error.

Where are the handles on this?

[guyer]

Confirmed that a new build does not run with Docs4NIST@0.6 ... I switched back to 0.5 and it runs, albeit with errors. But, at least I can now debug other problems besides the external xlrd reference.

Confirmed how? As seen in your package's Action summary, the commits that used Docs4NIST@0.6 succeed (green checkmark). The build where you backtracked to Docs4NIST@0.5 failed (red 'X'). The logs for both complain about xlrd, but the fact is that it's not required for Docs4NIST to run to completion; only for your package to be documented the way you configured it.

Nothing is showing up on pages.nist.gov because you still don't have a nist-pages branch. Alarmingly, you instead have pages-branch: 'master'. I am surprised (and a little disappointed) that this didn't completely destroy your repository. Create a nist-pages branch and leave the defaults alone.

[drfrpjr]

You are disappointed it did not destroy my repository?

[guyer]

OK, how do I give Sphinx xlrd in your Docs4NIST Python environment?

Specify the prerequisites for your package using a pip requirements file or a conda environment file. I acknowledge that the descriptions are terse.

Further, having done nothing to define the Python environment at all and it imports xml.etree.ElementTree without any error.

The xml package is part of the Python standard library.

Where are the handles on this?

What does that mean?

[drfrpjr]

I am backed up on a few pushes for the repo not related to the manual, That is why I did not create nist-pages yet. Closing the thread