Architecture & OSGi doc updates

[bwosborne2]

For the breadcrumbs I hope to move that into the header include using either php or JavaScript. I am thinking of making a JSON mapping file with the doc site structure to use for breadcrumbs & navigation. I expect to use php for the navigation sidebar.

One other navigation question. Some themes have a right sidebar showing header links within the page. Do you think that is needed? Some pages with tables get lengthy to navigate.

I fear I messed up & this PR includes the previous one. I am still learning...

[cdjackson]

I would not suggest to add the navigation to the files manually then - I think it's better to implement the infrastructure as we go rather than taking time to manually add stuff, then more time to remove it.

My suggestion is to avoid a json file, and the required js that is required to load it. If we can, there should be no reason not to have this pretty much as a static file that is generated when the docs are compiled - ie there's no need to generate a json file that is then loaded at runtime - just generate the header directly as static navigation.

The only thing that this doesn't work for is any sort of search capability, which might require something a little more "dynamic" - even if it's still largely static data.

If this has more included than you intended, is it better to close this, and for you to cherry pick the correct commits into a separate branch, and create a new PR?

[bwosborne2]

My suggestion is to avoid a json file, and the required js that is required to load it. If we can, there should be no reason not to have this pretty much as a static file that is generated when the docs are compiled - ie there's no need to generate a json file that is then loaded at runtime - just generate the header directly as static navigation.

For breadcrumbs you do not know until runtime what page is current. The heading file we currently use has the beginning html divs to minimize the html in the md file. That is why my current breadcrumb header is not extended across the top of the page. It only encompasses the article portion.

Since you had at least one complex html table with column spans, I have added some others because md does not support this feature. I agree we need to minimize html in the Markdown pages. In the future it may be possible eliminate the exisgin html with some magic from php or JavaScript.

[cdjackson]

For breadcrumbs you do not know until runtime what page is current.

What do you mean by this? Normally, this is just showing the hierarchy, which is known at compile time. Or do you mean to provide some sort of indication as to the browse history which I would agree is only known at runtime, but I don't really see the need for this.

I agree we need to minimize html in the Markdown pages.

I'm not against HTML in the pages. My point earlier was not against HTML tables, it was that putting all these navigation tables into every file doesn't seem like a good idea as it is manually generated and it really needs to be automatically generated to avoid it being a maintenance nightmare.

[bwosborne2]

Breadcrumbs usually stop at the current page & indicate it. That would likely need to be in the header include file. I guess it might be able to be injected into the html later, but I think the markdown page generator only allows for a header & footer include.

I figured once the idea or concept is validated manually, that portion could be automated. I am at that point now for breadcrumbs. I plan on manually experimenting with sidebars & get team comments before putting in automation work.

You do have a good point that the mapping is known at compile time. It will just take more work to automate that and I do not feel I yet have the needed knowledge.

[bwosborne2]

I am trying to break down PRs into smaller sections. Obviously this one combined 2.

If I keep working on ideas in my separate fork, it will eventually diverge to where a large, potentially conflicting, PR is needed.

[cdjackson]

More, smaller, PRs is generally better. You need to remember to always go back and use master as the base for any PR - so start in master, create a branch, make changes and commit them into that branch. Then go back to master and create a new branch for a different issue and repeat...

It should avoid divergence.

That said, if everything is "just" documentation, then it's probably find to keep it as a single PR. If you start mixing docs and code etc, I would suggest that in general, these should be separate PRs...

[bwosborne2]

The only place where both may be needed is if for a new feature. for instance. documentation needs to be updated. I see my work mainly on documentation right now.

I have ideas for a separate documentation repo with versioned docs sources from here to permit access to older released versions in the future.. It is best to build things out slowly though.

[cdjackson]

I have ideas for a separate documentation repo

As discussed, I prefer to keep the dev docs here so that features can be documented at the time of implementation.

with versioned docs sources

I would avoid this personally. This repo, if it contains the docs, will of course already be versioned. Putting them in another repo in my opinion is just a recipe for confusion. If we want versioned docs, which is definitely desirable, then it should be pulled from here, processed and the html created without an intermediate source of the documentation.

[bwosborne2]

I was thinking more about having the updated versions available. I guess whatever document automation could pull from multiple tagged versions of the core-repo.

[cdjackson]

I was thinking more about having the updated versions available.

I'm not quite sure what you mean - do you mean having a separate repository that can be updated outside of this? If so, I think that's a bad idea as it will lead to a configuration nightmare if the same docs are in multiple places.

Versioning is good - git is a versioning system - you can easily pull down different tags from this repository and process them for viewing on the web. I don't really see a need for another intermediate repository and I think that will lead to confusion.

I guess whatever document automation could pull from multiple tagged versions of the core-repo.

Absolutely - this is super simple to do in git.

[bwosborne2]

I removed breadcrumbs and changed FontAwesome version & icon.

It appears the others are passionate about the documentation system direction. I will stand back until a decision is reached on the system & doc format we will use for this project.

[cdjackson]

Bruce. As per the other discussion, I don't mind what format etc we use. I'm simply suggesting that we should avoid doing something temporary that will only cost time to implement and replace. Going through and manually adding all these headers to dozens of files, then having to update and remove them seems a bit pointless to me. There will for sure be errors in it - anything, by anyone, will have errors when trying to generate something like this by hand.

I would much rather prefer to see us spend some time to implement a "proper" system that compiles the headers from the source rather than requiring someone to do this manually and spending time to get it right.

I'm also not against versioning - quite the opposite - it's good and necessary. I simply prefer to avoid multiple repositories which will likely add confusion as to what repository is the base source, and therefore where people should implement changes.

It should be possible to have something along the following workflow - all implemented in a script, or maven, or something - I don't really have strong views on what tools are used either.

• Pull the docs from the source repo - change to the tag for the version being processed
• Process the MD/ASCIIDOC/Whatever into HTML. As part of this, add the headers, and navigation. This is all static, so can be generated during this compile process
• Iterate over this process for each version in the git repo - ie changing to a different tag, processing the docs for that different version into a separate folder/tree in the html output

The only other point is that it should fit in with the current site - so we should try and maintain a single set of common dependencies. eg Fabicon - unless there's a need to change to a new version, then let's stick to the existing one. If we need the new version, then let's change the whole site. Using two versions on the same page, doesn't make sense to me as it will slow down loading and increase resource use.

Sorry if my comments above are taken as meddling - I'm simply trying to help and I am not so worried about how this is implemented - just that we try and avoid wasting anyones time with temporary implementations, and we have a single source to avoid confusion.

[bwosborne2]

Your comments are not meddling. I have not really worked with sites built from source files and am still learning. I am confident I can use this system and make it work. So I can do temporary stuff but not push it here. That makes sense. As far as icons, FontAwesome did some major reorganizing for version 5 sand they are now pushing you to register even for free access. I have started looking at Google's materialize icons as an alternative elsewhere.

IMO the other suggested systems design the whole page, not easily permitting included header & footer files. A decision on the doc thread on the forum could help set clarity IMO.

[cdjackson]

FontAwesome did some major reorganizing for version 5 sand they are now pushing you to register even for free access.

but why change - V4 seems fine at the moment isn't it. If we change to V5, then fine, but it then needs to be coordinatored across the whole site, and if there's no need to change, then I'd suggest to leave as it is?

I have started looking at Google's materialize icons as an alternative elsewhere.

I use line awesome on another project, but again, I don't see a need to change here - it's quite a lot of work so there needs to be a benefit.

the other suggested systems design the whole page, not easily permitting included header & footer files.

I'm not sure what you mean by this? It should be easy to include the header and footer files - the system does this already and integrates in with the header and footer site navigation on the OSH website (at least I think it does - it did at one stage anyway). Note that it does assume that it is running in the OSH website though as it includes the header and footer that are in the OSH site, and are not part of this repository (as we discussed last week I think).

[bwosborne2]

I'm not sure what you mean by this?

Sorry, referring to the forum thread. At some time I also need to include my css file in this repo.

[bwosborne2]

Is this OK to merge now or would you rather it be closed & be part of a later docs PR?

[bwosborne2]

I think it is best to merge this later.