search

syndesisio / syndesis.io

The syndesis.io Website
https://syndesis.io
10 stars 33 forks source link

feat: render the user manual #158

Closed zregvart closed 3 years ago

zregvart commented 4 years ago

I'm creating a draft PR to gather some feedback, this is still very much a work in progress task.

Delawen commented 4 years ago 
$ gulp manual:export
[12:16:26] Using gulpfile /var/git/syndesis.io/gulpfile.js
[12:16:26] Starting 'manual:export'...
[12:16:26] 'manual:export' errored after 36 ms
[12:16:26] Error: Command failed: svn export https://github.com/syndesisio/syndesis/trunk/doc build/documentation --non-interactive --quiet --force
/bin/sh: 1: svn: not found

A small stupid thing, but make sure svn is installed where we build and deploy this.

zregvart commented 4 years ago

A small stupid thing, but make sure svn is installed where we build and deploy this.

Pushed https://github.com/syndesisio/syndesis-docs-builder-image/commit/2fdd2213ece4b385ec3b438e6ddc97fd5c43f1b5

Delawen commented 4 years ago

The "public" folder looks good to me, but I can't make the manuals work with a simple gulp or hugo command. Would that be an issue?

Delawen commented 4 years ago

Manuals have links to redhat.com manual pages about connectors. That's not good.

Delawen commented 4 years ago

Besides changing all references to redhat.com to local references, I would say this is fine.

zregvart commented 4 years ago

If you render the HTML into the content directory then Hugo is interpreting any template parameters (within {{ and }}). On my end this fails with:

Rebuild failed:

".../syndesis.io/content/manual/integrating-applications/index.html:3547:1": template: __/.../syndesis.io/content/manual/integrating-applications/index.htmlHTML:3547: function "name" not defined

3545 | <div class="listingblock"> 
3546 | <div class="content"> 
3547 | <pre>At {{time}}, {{name}} tweeted:
3548 | {{text}}</pre>
3549 | </div>
zregvart commented 4 years ago

I'm not a big fan of having "Documentation" and "Manuals" in top level navigation. I'd prefer only to have "Documentation".

Delawen commented 4 years ago

My idea was to separate "Developer" Documentation from Manuals for User and Sysadmins.

But yes, maybe it makes sense to have everything together.

zregvart commented 4 years ago

I've pushed the quick and dirty rendering of the manual in ce0a853. The styling is mostly off and we probably need to bring in more of the default Asciidoctor.js CSS stylesheet to make it work. Some issues that I'm aware of:

Delawen commented 4 years ago

About the links, I was going to change them replacing the attributes*.adoc files but I am not sure we have a published version of those links online.

zregvart commented 4 years ago

I don't think we can replace values in shared/attributes*.adoc without breaking the downstream build. I think we can override them instead. Besides the links in the attributes there are links to access.redhat.com in the adoc files themselves. Some of the attributes in shared/attributes.adoc and doc/shared/attributes-links.adoc don't seem to be used.

TovaCohen commented 4 years ago

Adding @MelissaFlinn Actually, you can edit the values of the attributes in the upstream shared/attributes.adoc file and the shared/attributes-links.adoc. Downstream, when we fetch upstream content, we do not fetch those files.

For example, downstream, we need {LinkFuseOnlineTutorials} to be set to the URL for that book in the Red Hat customer portal. But upstream, can you set that attribute to the Syndes web site documentation location? If you will need a specific file name, that might be a problem. But if you just need the URL for the documentation pge, and then the anchor ID of the content, this should work. Of course, the name of the attribute is a downstream name, but maybe there is something you can think of to address that.

Yes, there are attributes in both files that are not used in Syndesis content. We can help identify and clean out those files.

Delawen commented 4 years ago

Actually, you can edit the values of the attributes in the upstream shared/attributes.adoc file and the shared/attributes-links.adoc. Downstream, when we fetch upstream content, we do not fetch those files.

That's true. Also true for any Fuse direct naming or reference.

I don't think we should reference any explicitly Fuse doc here.We can (and should) on another section as external links, but not as part of the core documentation. It could be confusing if we start mixing Fuse and Syndesis as if you can't have Syndesis without Fuse.

TovaCohen commented 4 years ago

@Delawen - @MelissaFlinn and I certainly agree with you that Syndesis doc published on the community site should not reference Fuse. Melissa created this doc Jira to prepare the Syndesis doc for publishing upstream: https://issues.redhat.com/browse/FUSEDOC-3865.

MelissaFlinn commented 4 years ago

@TovaCohen Thanks! and @Delawen Yes - I am hoping to start on making some doc updates described in that JIRA. I am wondering how to coordinate with your effort in this PR. Any thoughts?

zregvart commented 4 years ago

I've published a quick preview here, showcasing what we currently have.

TovaCohen commented 4 years ago

It is great to see this early preview @zregvart ! I'm working on Debezium these days but I couldn't help but take a look. There are certainly many details still to work out, but just want to make sure you know that images are not being displayed. For example, in chapter 2 of the user guide, the general workflow and the example workflow have diagrams that are not appearing.

zregvart commented 3 years ago

@Delawen @kahboom I've found some time to finish this, sorry for lumping a lot of changes into one. Can you have a look?

zregvart commented 3 years ago

Oh, and I know that there are shortcomings, I'm hoping that we can do smaller PRs to fix those rather than lump everything in one big one. But do let me know if you disagree :)

zregvart commented 3 years ago

Merging, easy to revert. I'll work on improving this in smaller PRs.