Move / copy documentation from READMEs into the documentation project

[warriordog]

Readme files should be left with a useful summary and links to the documentation. The "Types" readme has a particularly large amount of content to move.

[Raithlin]

Are you expecting a complete rewrite, or (certainly to start with) a basic copy the contents of the existing readme file to github.io and leave a summary in readme.md? Following on that question, would the documentation retain the existing links to code? I've glanced at the current documentation which looks to be auto-generated. It would be immensely helpful if you had an example that we could start from.

Lastly, I'm assuming this would be updating the API Documentation section?

[warriordog]

@Raithlin My thinking was like this: To start with, just copy the existing readme files into the documentation. Then replace the original files with a small summary + link to the original. For the main repository-level readme, I'd prefer that it be left mostly unchanged, just make sure that all of the info is copied into the main docs somewhere. Then remove any minor details that don't need to be in the main file.

Does that sounds reasonable?

[Raithlin]

Let me see what I can do with that. I'll respond properly if/when I need more clarity.

[warriordog]

@Raithlin thank you so much!

[Raithlin]

Do you want to replace the existing documentation, append or insert the readme above the existing text?

[warriordog]

@Raithlin I was thinking of adding a subsection in the documentation somewhere, with package-specific info. Then the existing documentation could be inserted as new files there.

[warriordog]

This might help: https://warriordog.github.io/ActivityPubSharp/Contributing/contributing_to_documentation.html

It's a little out of date and is missing a lot of info, though.

[Raithlin]

I read that last night. 🙏 Right, if you can create a subsection I can get started (we can always rename it later, right?)

Perhaps this should go under Dev Resources - or its own subsection perhaps.

[Raithlin]

@warriordog Am I correct in thinking this belongs in Dev Resources? If I put it in API it'll be overwritten if I understand this right.

I'm looking at something like this:

| Overview -| ActivityPub.Client --| Overview -| ActivityPub.Common --| Overview

etc. Are you happy with this arrangement for the moment?

==EDIT== Alternatively we could look at something like including markdown files - creating a subsection within the API docs that would be auto-generated. we could move the content of the readme files to /include/* and insert them via the code files themselves.

[Raithlin]

Apologies - I'm getting to know DocFX. As I read further I find more ways to get things done.

[warriordog]

@Raithlin that structure works 👍