search

gridcf / gct-docs

Grid Community Toolkit documentation
http://gridcf.org/gct-docs/
1 stars 4 forks source link

Fix broken links and add api doc #9

Closed ellert closed 5 years ago

ellert commented 5 years ago

This PR

fscheiner commented 5 years ago

@ellert @matyasselmeci @msalle About the version numbers: Inside the API docs we still have the "Globus version numbers" (i.e. Major.Minor.Timestamp-of-last-commit) but the real API directories (/api/6.2.20181115 and /api/6.2.20190226) are using our tag version numbers. This could be confusing.

matyasselmeci commented 5 years ago

Can we do it the other way around and have the API docs use the tag version numbers somehow?

fscheiner commented 5 years ago

@matyasselmeci

Can we do it the other way around and have the API docs use the tag version numbers somehow?

That would be even better, though I don't know if that can be easily changed. Maybe by overwriting the PROJECT_NUMBER variable with the tag version number when building. But the binaries still retain the "Globus version numbers".

OTOH we could also just define the project number as: <TAG_VERSION_NUMBER> (<GLOBUS_VERSION_NUMBER), e.g. v6.2.20190226 (6.2.1550507116) or Tag: v6.2.20190226 (6.2.1550507116) or orderered vice versa. This would include both matching version numbers at the top of the API docs.

@ellert Could you please also describe how the API documentation is created (command line, needed tools, etc.)? Was this an elaborate process?

I'd like to add that information to a sort of release howto, maybe in the GCT or GridCF wiki. This should be a collection of what to do on a release (pmc vote, tag, documentation updates, announcement mail, etc.)

ellert commented 5 years ago

@ellert Could you please also describe how the API documentation is created (command line, needed tools, etc.)? Was this an elaborate process?

This is not complicated. Starting from the source distribution:

tar -z -x -f gct-6.2.xxx.tar.gz cd gct-6.2.xxx ./configure make doc

After which the documentation is available in doc/html.

There was a glitch in the 6.2.1550507116 tarball generation, so it needs an extra step to repair it before it can be used (this is fixed in git, and this step will not be needed for future releases):

tar -z -x -f gct-6.2.1550507116.tar.gz cd gct-6.2.1550507116 ( cd gsi_openssh/source/ ; aclocal ; autoheader ; autoconf ) ./configure make doc

fscheiner commented 5 years ago

@ellert Thanks, I'll incorporate that information.

ellert commented 5 years ago

I have no strong view on the directory names. I hope most people will use either the "latest" symlink to the latest release, or the "6.2" symlink to the latest 6.2.xxx release, and not reference the specific releases. We should choose one convention for the directory name and then stick to it. As I said, I have no strong preference on what names to use, but maybe it makes most sense to use the number that appears on the pages as the name of the directory. It is possible to create an /api/index.html page that provides longer descriptions, like e.g.

fscheiner commented 5 years ago

@ellert After I merged #11, I noticed a wrong version number in my changes. Your version of 6.2/gsic/index.html is the correct one. With https://github.com/gridcf/gct-docs/pull/9/commits/bc05fba35b8dd21455d0772a4044514bee0e634b applied, your version can be merged again and will correct my wrong version from #11.

ellert commented 5 years ago

When [gridcf/gct#83] is merged, could you recreate the API docs for our two releases and force-push the changes?

The PR above will be part of future releases. The API doc builds are created from the released source tar file, and approval of the PR will not affect the API doc builds of old releases. Unless it is backported. But do we want that?

I added an index page in the api directory that directs users to the right version if they have the tag name.

fscheiner commented 5 years ago

The PR above will be part of future releases. The API doc builds are created from the released source tar file, and approval of the PR will not affect the API doc builds of old releases. Unless it is backported. But do we want that?

Maybe not. I just thought you would checkout the tag, apply the changes just for the doc build and rebuild the docs. But that would be inconsistent, although only in the differing version strings.

I added an index page in the api directory that directs users to the right version if they have the tag name.

I'm fine with that.