[FEATURE] Migrate Docs from Documenter to DocumenterVitepress

[TheCedarPrince]

Issue Description

Difficulty: Beginner

Time: 6 - 8 hours

Description: The aim of this issue is to support the major refactor beginning across all of JuliaHealth to improve discoverability and unity of the JuliaHealth ecosystem as it pertains to documentation. This issue's purpose is to provide guidance on how one will migrate the IPUMS.jl documentation website built on Documenter.jl to DocumenterVitepress.jl to support a more winsome entry point to new Julians curious about health research within the Julia community.

Requirements

• Add DocumenterVitepress.jl dependency into the docs directory of this repository
• Migrate the Documenter.jl make.jl file to a compatible DocumenterVitepress.jl make.jl file
• Make sure each page renders correctly
• Open and submit a PR

Expected Outcomes

After this transition is completed, the website should go from looking like this:

To something more like this:

Additional Notes

For how to approach this issue, I would suggest the following steps:

First, if you have never worked with Documenter.jl before, I would highly recommend these videos and resources:

• Video: Documenter.jl Deep Dive
• Documentation: Documenter.jl Official Documentation

Next, I would recommend creating a practice folder (repository) on your computer to download Documenter to. From there, I would follow the above tutorials and guides to create a documentation website on your own computer from scratch. Once you know how to create a documentation website, how to add pages, and how to write documentation for the website, you are ready for the next step!

Second, I would then create a fork of the JuliaHealth website. Within this fork, I would add Documenter.jl to this fork. You can do this from within the Julia REPL.

Third, you will now need to begin migrating the make.jl file to DocumenterVitepress -- this guide by @Jay-sanjay is a great place to start. This will take some time and the way to preview the documentation locally can be a bit challenging. In case there are any problems, please see the resources section for help.

Third, once you are done with this, go ahead and open a Pull Request with all your changes saved to your fork. At this point, myself or @00krishna will review this PR to suggest changes or help.

Then, you should be done with this PR!

Other Resources

Julia Slack:

• documentation channel - you should post here first
• helpdesk channel - this would be to get more attention to your issue but maybe not as precise as you need.
• health-and-medicine channel - this is where most of JuliaHealth is located these days.

Julia Discourse - I would advise posting here if you have an issue that you feel is long or requires a lot of time to explain as you might lose it within Julia Slack. Consider cross-posting your forum post to the Julia Slack in helpdesk and/or documentation.

[00krishna]

Status so far. So there is an issue with DocumenterVitepress that @TheCedarPrince is tracking for resolution. The issue has to do with building the docs or the liveserver aspects.

@MichelaRocchetti and @00krishna were working on getting the basic Documenter.jl piece working. We were encountering some errors with generating the basic Documenter docs. Here is a paraphrase of the problem.

Basically in each of the generated openapi documentation files, there is a reference to a README.md that contains some specific sections. Here is an example.

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)

So the README is supposed to have sections #api-endpoints and #models, but our current README does not have these files in it. These are not the only sections, as some of the generated docs look for other sections in their corresponding README.md files. Do you know if there was a README.md generated during the openapi build process that was possibly discarded or something?

Like even in the openapi docs, it was really hard to figure this out. There is no mention of the README files, but in the openapi docs itself, the corresponding README files is not in the docs section of their repo, but it is in their test section. So really strange, haha. It is like they did not want anyone to know, but it is necessary to test with the README.

So the next steps are to check with the OpenAPI folks about where this README.md file should be, and what sections it should contain.