Core: Bundled docs missing in release

[PVince81]

Steps

1. Extract the ownCloud 10.1.0 tarball.
2. Check "core/doc" folder

Expected result

Docs are there.

Actual result

They aren't, only index.html.

Version

ownCloud 10.1.0 Community and Enterprise bundles.

In the old versions 10.0.10 of the tarballs the docs are there.

Since we migrated to a new documentation format, we'll need extra steps to make sure the documentation is correctly bundled as it was before.

Now bundling the new one is likely not only a matter of putting the files there, we should also check that it properly renders in the UI.

Alternatively we could also decide to remove the bundled documentation altogether.
The various links inside of ownCloud are already pointing at the online documentation instead of the bundled one.

@settermjd @pmaier1 @hodyroff thoughts ?

[ownclouders]

GitMate.io thinks possibly related issues are https://github.com/owncloud/core/issues/12665 (Docs), https://github.com/owncloud/core/pull/31265 (Fix missing exception doc), https://github.com/owncloud/core/issues/55 (Missing translation), https://github.com/owncloud/core/issues/66 (Icons missing), and https://github.com/owncloud/core/issues/21164 (Admin manual missing from releases).

[PVince81]

@tboerger @settermjd the docs used to be built as part of the release process by running the scripts from the Makefile from https://github.com/owncloud/documentation

Should we add Antora / docker / etc and everything needed to the old release script to build the HTML admin and user docs for bundling, or should the docs be prebuilt and delivered for download under a known URL ? (maybe zip or tar that can be extracted during release build)

[PVince81]

This is how it looks like for 10.1.0 on my server:

[PVince81]

the third alternative is removing the bundled docs and have the "Help" menu entry on the top right point directly at the online docs...

[PVince81]

I had a quick look and it looks like the antora docs currently would build all of the manuals, not only admin or user. Also there will likely be a problem with URLs as those would expect to be deployed under a specific subfolder. These need to be remapped at build time to allow for deploying inside of OC.

From my understanding this might need an alternative site.yml specific to the OC build ?

[settermjd]

@PVince81, I'll see what I can do to make the bundled docs gr8 again!

[settermjd]

I'm experimenting with updating core's Makefile to build the docs locally. However, if it takes too long, likely the best solution would be just to point to the online docs. They have a whole build pipeline after all.

[settermjd]

Actually, thinking about it further, why not just take the simplest path and link directly to the online docs? No need to maintain the docs in two places.

[PVince81]

Actually, thinking about it further, why not just take the simplest path and link directly to the online docs? No need to maintain the docs in two places.

this would be a PM decision as there might have been reasons to bundle the docs in the past, maybe for offline instances.

@pmaier1 @hodyroff what do you think ?

[DeepDiver1975]

Actually, thinking about it further, why not just take the simplest path and link directly to the online docs? No need to maintain the docs in two places.

:+1: the bundled docs will be out dated the day we ship them in the release. And they will stay there for years. Kill them!

[PVince81]

• [x] check if EE also has this section => was told it doesn't

[PVince81]

as discussed with @pmaier1 and @cdamken we decided to not bundle it any more.

it's not used in EE, only CE.

[PVince81]

I'll take care in next sprint, there's some code in core to delete...

[PVince81]

@sharidas please take care. compare EE with CE in terms of bundled docs and then delete all related code in CE so that the section disappears, just like on EE.

[sharidas]

EE does not have:

• Help, using which user can navigate to the bundled docs.

CE does have:

• Help, with links.

Objective:

• Remove the Help from the CE.

[sharidas]

Created PRs here:

• [x] master branch PR https://github.com/owncloud/core/pull/34611
• [x] stable10 branch PR https://github.com/owncloud/core/pull/34612

[PVince81]

we still have this PR for rewiring the doc links:

• [ ] https://github.com/owncloud/core/pull/34586