Create GH-pages to host the docs

gfoidl commented 3 years ago

Can use something like https://dotnet.github.io/docfx integrated in CI/CD to push to gh-pages branch when built from main.

gfoidl commented 3 years ago

I believe GH-pages doesn only work for public repos (or for the paid team-accounts).

So as first spike: https://mycsharptest.z6.web.core.windows.net

@BenjaminAbt what do you think of this generated content? I don't like to put too much time into this with styling, etc. Once I send a PR, then CI builds it from main (and when possible pushed to the gh-pages branch).

BenjaminAbt commented 3 years ago

We put this repo public asap...?

BenjaminAbt commented 3 years ago

But dont know if we really need GH docs, our lib is very simple and limited? :-) But generated code looks okay.

gfoidl commented 3 years ago

We put this repo public asap...?

Once we did https://github.com/mycsharp/HttpUserAgentParser/issues/7 (in anyway) I'm OK with making it public.

But dont know if we really need GH docs

No we don't need it. But

NuGet / .NET plans to introduce a score for packages and having good docs gives better points, so better ranking in NuGet-search
quite some devs base their criteria on using a lib or not on api-docs via gh-pages (sometimes I do this too to see if they took it serious)
the effort for this so far is copy & pasting + little edit from another project

For CI/CD I did this with AzPipelines, should be quite similar for GH-actions.

I don't know. But as the effort is little, I'm leaning towards publishing gh-pages.

BenjaminAbt commented 3 years ago

In my eyes #7 is just a nice to have, because it's not in our responsibility as we just use external APIs.

NuGet / .NET plans to introduce a score

So we fight for a ranking....for a tiny lib? What are our competitors, I dont get it..?

gfoidl commented 3 years ago

it's not in our responsibility as we just use external APIs.

We set a sizelimit, so each entry needs to set it too, otherwise: bang exception So at least we are responsible to document it, as the default DI will inject the shared IMemoryCache. This would crash our portal, too. Other options listed in that issue (why not comment over there?).

So we fight for a ranking....for a tiny lib? What are our competitors, I dont get it..?

OK, let's forget it. (So why xml-docs at all?)

BenjaminAbt commented 3 years ago

OK, let's forget it. (So why xml-docs at all?)

To avoid warnings during build :-)

Jokes aside. I am welcome to add GH Docs, I have no passion for that at all.

I'm just a big opponent of work that is unnecessary. Hence the very minimalist summary documentation. I don't have time for that. And I will not invest any time for something like that. I'd rather invest it in content.

gfoidl commented 3 years ago

Just remove https://github.com/mycsharp/HttpUserAgentParser/blob/44d7ed94e404ce5d7cfa648fb7103434499d86f6/Directory.Build.props#L22-L24 then there won't be any warnings 😉

BenjaminAbt commented 3 years ago

The core of the library is a single line (HttpUserAgentParser.Parse) of code, documented by the readme alone.

A 100% solution is a worthy goal, but other tasks should have a higher priority. Let's focus on the content, everything else will come with time.

Let's put the thing public, build it into the portal and then we have an 80% solution that will last for 99% for the next weeks/month/decades

gfoidl commented 3 years ago

Let's put the thing public, build it into the portal and

should get an exception because of #7.

mycsharp / HttpUserAgentParser

Create GH-pages to host the docs #8