Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix broken link in to Cirque documentation #6862

Closed

Conversation

neonsoftware
Copy link
Contributor

Problem

The user, when cliicking on the link to the Cirque's README documentation page, was landing on a 404 Github page, due to an invalid relative link.

Summary of Changes

The link is fixes, and the documentation navigation is now working correctly.

@boring-cyborg boring-cyborg bot added the documentation Improvements or additions to documentation label May 16, 2021
@neonsoftware neonsoftware force-pushed the fix-doc-cirque-link branch from 79da4a5 to 78df0f8 Compare May 18, 2021 16:03
@neonsoftware
Copy link
Contributor Author

Status
The GIthub doxygen workflow reported the following issue:
/home/runner/work/connectedhomeip/connectedhomeip/docs/README.md:9: error: unexpected token TK_EOF as the argument of ref (warning treated as error, aborting now)

Although launching locally ./scripts/helpers/doxygen.sh the doxignen generation was successful and the link working.

Action
Investigating why the doxygen is failing on the Github workflow (and not locally). I have re-uploaded the commit with a freshly re-modified line, in case it was an issue with encoding.

@bzbarsky-apple
Copy link
Contributor

Investigating why the doxygen is failing on the Github workflow (and not locally)

What version of doxygen are you running locally? This looks a lot like doxygen/doxygen#8130 which was just fixed a few months ago. Fix is in doxygen 1.9.0, but our containers are running doxygen 1.8.17, afaict.

@neonsoftware
Copy link
Contributor Author

Hi @bzbarsky-apple,
Spot on. I run 1.9.1 locally.
And, yes, Github offers up to Ubuntu 20-04 on workflows, while 1.9.x is only from ubuntu 21-04.
It might be that.

Before I make any correction, what do you think, or any other of the project of course, would be the best way forward ?

  • option A: in the Github workflow, I will add a temporary step, with bash doing if(doxygen version < 1.9.x) { install doxygen from ubuntu 21-04 }, marking such workflow step with a comment, capital letters, "this step can be removed once default doxygen version will be 1.9.x"
  • option B: as option A, still manually upgrading doxygen in the workflow, but better, looking forward any idea or suggestion
  • option C: asking the doxygen project a backport of the fix to 1.8.17+ and putting this issue on hold until available
  • option D: none of the above and deleting this issue
  • option E: any other option that I might have not considered yet, let me know

Considering that with option C and D the documentation has broken links in this phase of adoption.

Let me know, cheers, have an outstanding week, F

@bzbarsky-apple
Copy link
Contributor

My gut feeling is that if we can do the doxygen update in our container in general, not on a per-workflow basis, that would be ideal. I guess that's option B, right?

@woody-apple How feasible is that?

@electrocucaracha
Copy link
Collaborator

I have created this PR to automate the validation of broken links, hopefully that helps to early detect these issues.

@neonsoftware
Copy link
Contributor Author

@electrocucaracha great.

@woody-apple
Copy link
Contributor

/rebase

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation review - approved
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants