How Can I Compile and Test dotnet-api-docs?

[JoanGil]

Hello!

I'd like to contribute to this repo, and I've already opened an issue. I've also reviewed some of the readme files but couldn't locate any instructions on how to test the entire repository (dotnet-api-docs). It would be greatly appreciated if someone could assist me with this. I'm eager to ensure that the changes I make are visually appealing and that the project compiles without any broken references.

Thank you in advance!

[ghost]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[antonfirsov]

@gewarren @carlossanlop any advice on this? Personally I usually just go ahead with PR-s, and rely on the validation actions executed there.

[carlossanlop]

@JoanGil thanks for offering to help!

I once tried to build the repo locally, like 2 or 3 years ago, and it took about 5 hours to complete. It's not worth it.

We prefer to rely on the PRs because the CI is powerful:

• It'll finish building only your changes in a short period of time.
• It will tell you if there are any suggestions, warnings or errors that you need to address.
• If the build is successful, you'll get a link to a test website that mimics Learn (formely MS Docs) but showing your changes as they would look in the final product.

The main problems we see that the CI catches for you are xml syntax errors (which you can usually avoid by using an IDE that supports xml syntax, like VS Code), or incorrect references to API docIDs, which you can address easily by obtaining the right string from the xml of the actual API that you're trying to link.

If you tag me and @gewarren to your PRs, we'll be happy to guide you and give you explanations of every problem for which you have any questions.

[JoanGil]

Thanks @antonfirsov for forwarding the question and many thanks @carlossanlop for explaining the steps. I will certainly try to do as you suggest and most probably tag you to double check. Thanks again to both of you!

I am gonna close the issue since I got a great answer!

[JoanGil]

@JoanGil thanks for offering to help!

I once tried to build the repo locally, like 2 or 3 years ago, and it took about 5 hours to complete. It's not worth it.

We prefer to rely on the PRs because the CI is powerful:

• It'll finish building only your changes in a short period of time.
• It will tell you if there are any suggestions, warnings or errors that you need to address.
• If the build is successful, you'll get a link to a test website that mimics Learn (formely MS Docs) but showing your changes as they would look in the final product.

The main problems we see that the CI catches for you are xml syntax errors (which you can usually avoid by using an IDE that supports xml syntax, like VS Code), or incorrect references to API docIDs, which you can address easily by obtaining the right string from the xml of the actual API that you're trying to link.

If you tag me and @gewarren to your PRs, we'll be happy to guide you and give you explanations of every problem for which you have any questions.

I reopened the issue because I believe it could be valuable to include your explanation in the README. This way, anyone interested in collaborating on this repository will know the initial steps to get started. If you agree, I can create a pull request that incorporates the explanations you provided into the initial README page. Is that acceptable to you, @carlossanlop?

[JoanGil]

Any idea on this @carlossanlop? If you don't agree I could just close the issue 😃

[carlossanlop]

I can create a pull request that incorporates the explanations you provided into the initial README page. Is that acceptable to you, @carlossanlop?

I wouldn't mind. @gewarren, would you approve such addition to the documentation of this repo?

[JoanGil]

Nice, thanks @carlossanlop. I am gonna wait until I have green light from @gewarren.

[gewarren]

All of our other contributor guidance is here, which is linked from CONTRIBUTING.md. So I think it's better to add the information there.

[JoanGil]

All of our other contributor guidance is here, which is linked from CONTRIBUTING.md. So I think it's better to add the information there.

Okay. I will put the information in CONTRIBUTING.md and I might also add a short explanation or link in the README.md so it's easier to find. I will tag both of you in the merge if that's okay!

[gewarren]

Sorry, I meant the contributing info should go here: https://learn.microsoft.com/contribute/content/dotnet/dotnet-contribute.

[JoanGil]

Okay. Thanks for clarifying. Then maybe it's clear enough. I still think that it might be interesting to have a bit more of information or links on the readme or contributing guide.