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

deprecate AppendDoxref() #1

Open
garyjg opened this issue Jan 12, 2024 · 0 comments
Open

deprecate AppendDoxref() #1

garyjg opened this issue Jan 12, 2024 · 0 comments
Assignees

Comments

@garyjg
Copy link
Member

garyjg commented Jan 12, 2024

AppendDoxref() was an attempt to allow source dependencies to add doxygen tag files to an Environment variable DOXREF so doxygen apidocs builds could link to the apidocs pages of dependencies. For example, where the logx library uses a log4cpp type, the logx html apidocs would link those type names to the log4cpp documentation. This was difficult to make flexible and robust. The tag files for external dependencies have to be updated, both to match the version of the dependency and the latest location of the generated html files. For internal dependencies, like for aeros documentation to include the logx libraries, then the logx apidocs builder had to build the tag file and then supply it to the parent. And for all this complication, I don't think anyone really uses or relies on the tag references. Probably the apidocs themselves are not used as much anymore.

External references will probably never work, and might be better replaced with a link in the project's top-level documentation to the online documentation for each of the project's external dependencies.

The more recent approach to project-wide documentation for all internal references is to accumulate all the doxygen sources from the subdirectories and generate one Doxyfile which scans all of them. ASPEN uses this approach.

So this issue is to consider deprecating and eventually removing all the AppendDoxref() code. Start out with keeping the Environment method but making it a no-op, while removing all the uses of it in the doxygen.py tool.

@garyjg garyjg self-assigned this Jan 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant