Reconsider keeping this project in a separate repository.

[tdstein]

While integrating this project into the Connect docs build process, I uncovered various oddities that made me reconsider the value of keeping this project separate from Connect. In particular...

• The configuration of sidebar links requires non-obvious settings. Furthermore, Connect does not use the link configuration in this project. Connect has its sidebar link configuration, mimicking this project, but it is different.
• Links to other parts of Connect do not work in this project. Obviously, we cannot correctly render links from this project that reference something in Connect docs, such as /api or /admin.
• There is no link validation in this project. If we were to add it, it would not work as intended due to the issue above.
• An original goal for this project was to configure CI tests to evaluate the correctness of examples. This idea hasn't come to pass. It's possible to do it, but it isn't immediately viable. And there is no reason this can't be done within the Connect repository.

If we decide to migrate this project back to Connect, the main drawbacks are...

• Executing quarto preview in Connect is significantly slower (maybe a minute; I haven't timed it). I'm unsure if there is a workaround since this is Quarto behavior. This only matters on the first run. Subsequent runs only analyze changes.
• Contributors must understand a more complex build process. But to thoroughly test any changes to this project, you also need to run that build process anyway to verify that it renders correctly in Connect.

[tdstein]

@aronatkins was kind enough to put together a short list of other improvements that could be accomplished as part of this effort if we explore this issue further:

Build overview

1. config_doc is used to generate the configuration appendix (and confirm that all sections are included); produced by the Connect build.
2. auditing_doc used to generate the auditing events section; produced by the Connect build.
3. api_codes used to generate the API error codes HTML; produced by the Connect build.
4. linkwalk used to test links; produced by the Connect build.
5. rstudio/connect:docs used to build docs; assumes folks have Docker Hub access.
6. rstudio/connect:test-api used to generate API documentation; assumes folks have Docker Hub access.
7. rstudio/connect:test-api is used both for generating the API spec and running our API tests, which means it’s heavier than needed.

Other considerations

• Migrate from Swagger to OpenAPI for the API reference.
• Migrate from linkwalk to htmltest: https://github.com/rstudio/connect/issues/26686