Produce FSdcos Documentation for v0.1

[HarryMcCarney]

This should include section on creating graphs from edge lists and running basic operations and algorithms in an fsx environment.

[HarryMcCarney]

Hi @kMutagene

I am trying to generate the docs on branch version/0.1.0. The html files appear to generate correctly but the code comments docs dont seem to be accessible from index.html when running with dotnet fsdcocs watch --eval

I am generating the docs with .\build.cmd PreRelease

Please let me know what I am doing wrong.

Many thanks, Harry

[kMutagene]

If you want to watch the docs locally, i'd suggest using ./build.cmd watchdocs. I think the main difference is that using this buildchain it is made sure that the dlls are built and accessible for api docs generation. At least for me, this is how the api reference looks like on the branch you specified:

For the best results, API docs should be written in the .NET XML doc format. See for example here in plotly which generates this page: https://plotly.net/reference/plotly-net-chart2d-chart.html#Point

Also, new documentation files will not show up on the index page during a watch session. So if you add new docs pages, you have to re-run the watch command (or manually type the url of the new file).

[HarryMcCarney]

Hi Kevin,

I have just released version 0.1.0. It seemed to work fine and the package is published to nuget.

But I can't access the docs. The GH Action logs say they are published to https://fslab.org/Graphoscope/ but I get a 404 on that URL and on https://fslaborg.github.com/graphoscope/

I also made the repo public as it doesn't seem possible to use GH pages in a private repo, and now we have an initial version, I think its time.

Please let me know how I can resolve this.

thanks! Harry

[kMutagene]

It seems like you are pushing commits to gh-pages that are not on main. I would not recommend this. The workflow of publishing docs with the current repo setup should look like this:

• commit documentation on main (or another feature branch)
• from that branch, either release docs via the releaseDocs build target, or set up a github action that releases docs on commit.
• for both of these, gh-pages should be an orphan branch, meaning there are no other commits than genereated documentation. This is also why the current setup does not work. The pages and source files are on wrong paths on the current gh-pages branch

So, we can fix this via:

• moving all the documentation commits (WITHOUT the 'updated generated documentation for v XYZ' commits) onto main (or v0.1, whatever is the current branch you want to publish docs for)
• delete the current gh-pages branch
• push a properempty orphan branch to gh-pages
• release docs either via build target or github action

[kMutagene]

So i'd suggest you move everything you added on gh-pages to your target branch and i'll take care of the rest

[kMutagene]

It also seems like fsdocs artifacts ended up being committed to multiple branches. Looks like i forgot to add those to the gitignore

[DoganCK]

Hi @kMutagene, we managed to publish something on Doc Page. Although we changed the in fsproj to the correct location, it still seems to try load dependencies like css files from a github page. Any quick fix for that? Do we need to reinitialize the gh-pages branch or something?

Thanks

[kMutagene]

@DoganCK Which command did you use to publish the current state of the docs and on which branch? I'll try to reproduce this locally.

[DoganCK]

@kMutagene we used ./build.sh releaseDocs on the main branch. The locally generated output seems fine. But the documentation doesn't seems to update the root folder.

[kMutagene]

It looks to me like you changed the PackageProjectUrl tag to the correct url

https://github.com/fslaborg/Graphoscope/blob/317ffe721fbaa366cbce2426c88dac2f2b571599/src/Graphoscope/Graphoscope.fsproj#L11

on main, but published the docs from the another branch, where it is still on the github url. Because if I just do build.cmd builddocs (which is the output that gets pushed to gh-pages), i get the correct urls in the generated files.

I tried a run of build.cmd releasedocs from main, and it looks like the issue is resolved. So if you want to publish docs from another branch, you have to adopt the correct url that you fixed on main, see the current deployment on https://fslab.org/Graphoscope

[kMutagene]

However now it looks like the evaluators are not working, looking into it

[kMutagene]

Oh, one of the reasons might be that this file is missing for me:

let file = "C:/Projects/Doodles/out.moreno_rhesus_rhesus.txt"

can you commit that file to /docs/data ?

[DoganCK]

Thanks @kMutagene ! here's the file

[kMutagene]

Sorry i forgot the other one, the karate dataset is missing as well

[DoganCK]

Added. https://github.com/fslaborg/Graphoscope/tree/main/docs/data

zachary.txt is the karate data

[kMutagene]

I created 2 PRs that should fix any issues we currently see (see the current deployment at https://fslab.org/Graphoscope).

[DoganCK]

Thanks @kMutagene !