search

opencpn-manuals / plugins

Part of opencpn-manuals/main, not maintained as a separate manual
4 stars 3 forks source link

Navigation Bar - Use nav.adoc always in left nav bar #78

Open rgleason opened 3 years ago

rgleason commented 3 years ago

Maybe it is personal preference, but I like the Righthand Nav bar the way you've got it setup for the Internal Plugins which uses the expandible format that is setup in nav.adoc. Screenshot (310)

I realize that for some reason when we select an external plugin, the right hand navigation bar changes. Is there a reason for this? Isn't there some way to keep the nav.adoc version here? (prefered IMHO). Is there a reason to show this less versatile nav? Screenshot (308)

Note. I will be pushing the Simplified Navigation shortly, so wait a bit on this problem. Thanks.

rgleason commented 3 years ago

Maybe we can get the nav.adoc to be used in the Left hand navigation bar, for all plugins, by editing this antora?

│ ├─── ROOT <---Where all navigation for Plugins is done │ │ ├───── nav.adoc <--Uses partials files nav-main.adoc, nav-beta.adoc, nav-all.adoc. Left hand Nav bar │ │ ├───── antora.yml

and adding some directions that work? I am not not that familiar with this....

but what is used in the left hand navigation bar when an external plugin is showing in the center? We want to change whatever that is, so that nav.adoc is used.

rgleason commented 3 years ago

Here are two live examples:

Internal Plugin: Dashboard using nav.adoc for the Navigation Bar https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/dashboard/dashboard.html

External Plugin: oeSENC using something else for the Navigation Bar https://opencpn-manuals.github.io/plugins/oesenc/0.1/index.html

We want all external plugins to use nav.adoc in the Navigation Bar for consistency.

rgleason commented 3 years ago

I think I know what is happening. The external plugins are all under "sources" directory.

..plugins\sources\<plugin_name_pi>i\manual\modules\ROOT\pages\index.adoc

There is an antora file just above modules that generally reads

name: autopilot_route
title: Autopilot Route
version: '0.1'

and the site.yml next to it does not have any nav designation.

site:
  title: Autopilot Route
  url:  https://nowhere.net
  start_page: autopilot_route:ROOT:index.adoc

Perhaps we could figure out the correct path for the

nav: - ????

Field to point to

`..\manual\plugins\modules\ROOT\nav.adoc

so the nav bar stays the same. We would then have to get all distributed plugins using this, but over time it would get fixed. `

rgleason commented 3 years ago

Mike, I am running some tests to see if we can get the Left Navbar used all the time. Started by adding a nav: to

_sources\watchdogpi\manual\antora.yml

so that the nav.doc in

..\manuals\plugins\modules\ROOT\nav.adoc is used.

It does not seem to be changing the Left Nav bar however, Any idea.s? Path wrong?

Plugin Sources

OM-plugins\sources\watchdog_pi\manual\antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
  - ::manual/plugins/modules/ROOT/nav.adoc <---WHAT I AM TRYING  IS THIS PATH WRONG?

OM-plugins\sources\watchdog_pi\manual\site.yml

site:
  title: Watchdog
  url:  https://nowhere.net
  start_page: watchdog:ROOT:index.adoc
content:
  sources:
    - url: ../
      start_path: manual
      branches: HEAD
      edit_url: https://github.com/opencpn-manuals/watchdog_pi/edit/master/{path}
ui:   
  bundle:
    url: https://gitlab.com/leamas/antora-ui-default/-/raw/master/latest/ui-bundle.zip
    snapshot: true
output:
  dir: ./docs
  clean: true

Navigation and other documentation section

OM-plugins\site.yml

Big main site.yml

site:
  title: OpenCPN
  url: https://opencpn-manuals.github.io/plugins
  start_page:  opencpn-plugins::index.adoc

content:
  sources:
    # Keep listed sorted to avoid duplicates and for better diffs.

   - url: sources/watchdog_pi/
      branches: master
      start_path: manual
      edit_url: https://github.com/rgleason/watchdog_pi/edit/master/{path}

OM-plugins\antora.yml

name: opencpn-plugins
title: OpenCPN Manuals
version: '0.1'
start-page: manual/plugins
nav:
  - modules/ROOT/nav.adoc  <---Existing which works for most of the Left nav bar

OM-plugins\manual\plugins\antora.yml

name: opencpn-plugins
title: OpenCPN Plugins
version: '0.1'
nav: 
- modules/ROOT/nav.adoc    <---Existing which works for most of the Left nav bar

OM-plugins\manual\plugins\modules\ROOT\nav.adoc

Full path to nav.adoc

rgleason commented 3 years ago

Have also tried watchdog's antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
  - manual/plugins/modules/ROOT/nav.adoc

Still does not use OM-plugins/manual/plugins/modules/ROOT/nav.adoc

rgleason commented 3 years ago

Have also tried watchdog's antora.yml

name: watchdog title: Watchdog version: '2.4.29' nav:

Still does not use OM-plugins\manual\plugins\modules\ROOT\nav.adoc

rgleason commented 3 years ago

Have also tried watchdog's antora.yml

name: watchdog title: Watchdog version: '2.4.29' nav:

Still does not use OM-plugins\manual\plugins\modules\ROOT\nav.adoc

What am I missing here?

leamas commented 3 years ago

https://docs.antora.org/antora/2.3/navigation/xrefs-and-link-text/

rgleason commented 3 years ago

Thankyou Alec, that was helpful and I have read a number of other pages, but I haven't found the answer to this particular case. There are some very interesting diagrams here when you zoom in on the diagram it helps.

I clearly do not understand antora that well.
Last night in desperation I tried

  1. copying modules/nav.adoc and modules/partials into sources
  2. add an antora.yml that would use that new nav.adoc

for the left hand navigation of all the plugins documentation. It has not worked, antora site.yml completes but the left nav still refers to the plugins antora.yml.

I tried a number of variations. I guess I still do not know what the hierarchy is that triggers the use or non use of nav stuff. If you guys have any insights into this that you could share it would be helpful.

I am now considering trying to move all of "sources" to be under "modules" alongside of the other documentation that does work with the left side navbar. What are the problems with this? (Yes I know scripts would have to change.)

├───manual
│   │   .gitignore
│   │   .nojekyll
│   │   beta_plugins.txt
│   │   dokuwiki plugins.txt
│   │   README.md
│   │   ui-bundle.zip
│   │
│   └───plugins
│       │   antora.yml
│       │
│       └───modules
|             |───sources      **<--- TO  HERE**
|             |         ├─ .gitkeep
|             |         ├─DR_pi
│           ├───advanced
│           ├───authoring
│           ├───chart_downloader_tab
│           ├───dashboard
│           ├───grib_weather
│           ├───misc
│           │
│           ├───ROOT
│           │   │   nav.adoc
│           │   │
│           │   ├───pages
│           │   │       index.adoc
│           │   │       index-main.adoc
│           │   │       index-beta.adoc
│           │   │
│           │   └───partials
│           │           nav-all.adoc
│           │           nav-beta.adoc
│           │           nav-main.adoc
|           |
│           ├───sat2chart
│           └───wmm
└───sources      **<--- FROM HERE**
    │   .gitkeep
    │
    ├───DR_pi
leamas commented 3 years ago

Your problem is not about navigation, your problem is that you need to make cross-module xref link i . e., a link to a pacge in another module.

https://docs.antora.org/antora/2.3/page/page-id/

rgleason commented 3 years ago

In sources\watchdog\manual\antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
 - xref:ROOT:partials:nav-all.adoc

Have tried 

nav:
 - xref:ROOT:nav.adoc

Have also tried

nav:
  - xref:manual:plugins:ROOT:nav.adoc

nav:
  - xref:plugins:ROOT:nav.adoc

nav:
  - xref:plugins:ROOT:nav.adoc

nav:
  - xref:ROOT:nav.adoc

nav:
  - xref:nav.adoc

The file I am trying to cross reference to or xref is OM-plugins\manual\plugins\modules\ROOT\nav.adoc so that all the nav files will be used in the left side navigation for all plugins.

Any thoughts about what I am doing wrong?

rgleason commented 3 years ago

Also tried

nav:
 - xref::manual:plugins:ROOT:nav.adoc

nav:
 - xref::plugins:ROOT:nav.adoc

nav:
 - xref::ROOT:nav.adoc

nav:
 - xref::nav.adoc
rgleason commented 3 years ago

Some References

Compose navigation files across components

Composing navigation files in Antora using the include macro

Multi repository architecture documentation with Antora and ARC42 - Part 1

Couchbase Component Structure and Configuration

Link to a Page in a Different Component

Awesome Antora: Sort and hide components and versions

Antora top navigation bar customization

Antora 101: The Three Core Concepts You Need To Know To Use It Fully

https://github.com/anoff/blog/tree/master/static/assets/antora-arc42/

rgleason commented 3 years ago

Site Page Links

Whether in the body of a site page (i.e., AsciiDoc document stored in /pages), or in a navigation file, always create page-to-page or navigation-to-page links using the page cross reference syntax. Antora’s page IDs are what allows your site to be portable across environments, domains, and versions.

rgleason commented 3 years ago

Xref pages from other docs components

When the current and target pages belong to different docs components, you must, at a minimum, specify the target component, module, and page coordinates. You’ll almost always specify the target version coordinate, too. Example 1. current-page.adoc

xref:version@component:module:target-page-filename.adoc[link text]

rgleason commented 3 years ago

Now I realize that if we are able to get sources\watchdog\manual\ (for example) to use manual\plugins\modules\ROOT\nav.doc but then plugin devs will not be able to build their own documentation locally with antora site.yml !

Unless the antora.yml file can have a conditional nav: parameter.

leamas commented 3 years ago

Unless the antora.yml file can have a conditional nav: parameter.

Which it cannot have. I have already told you this: making the plugins depend on opencpn-manuals/plugins is a Bad Idea, and the whole focus of this issue is IMHO wrong for this reason. The price to pay in terms of complexity and circular dependencies is just not worth the benefits of a uniform navigation tree. I'm pretty convinced that we will end up in having this as it is after walking in circles for some time.

But OTOH, there might be some solution I havn't thought of. And if not else, you might read up on Antora.

leamas commented 3 years ago

As for your failing xrefs: please read up on Antora page ids and how they are defined, clearly stated in link in my previous post https://github.com/opencpn-manuals/plugins/issues/78#issuecomment-930482882. You must obviously state the component name since the xref references another component than the plugin.

Rasbats commented 3 years ago

Why not just https://opencpn-manuals.github.io/main/ocpn_draw/0.1/index.html[oDraw]. The 0.1 is not going to change anytime soon.

rgleason commented 3 years ago

Alec, it took me a lot longer to arrive at that conclusion, but I believe Mike has changed the ground here.

Mike that makes a good deal of sense to me. The authors can build without the nav left bar and we are reading documentation. Did you just remove the antora file in the plugin?

Then it might be possible when collected together, to have a single antors.yml pointing to the nav.adoc.

Alec I have tried every combination for this and I am not going to waste any more time on it. It just will not find nav.adoc with sources out in left field. I dont believe it is considered a component.

Rasbats commented 3 years ago

Did you just remove the antora file in the plugin?

The plugin was not touched in any way. https://opencpn-manuals.github.io/main is available for any plugin author to use.

rgleason commented 3 years ago

Oh, I was viewing these responses on my cell phone, which obviously, removed or changed the Left Nav so that it was not to the side. Now in my PC the Left nav is showing as usual.

Is it possible to have an antora.yml over-ride one that is lower down, so that PI Devs can still build (antora site.yml) and the final "Plugin Manual Book" gets the same nav.adoc Left panel all the time? For Example:

sources\antora.yml needs (as Alec says) to have a properly working cross-module xref link provided it will over-ride the antora lower down.

  1. the target antora file contains a "name key"
  2. manuals\plugins\modules\antora.yml contains "name"opencpn-manuals"
  3. so the sources\antora.yml should have nav: - xref:opencpn-manuals:ROOT:nav.doc ??

Forgot the xref!

rgleason commented 3 years ago

Well I tried the above and we still get the same Left Nav bar. Do I have the Nav page ID and Cross Reference right? I think I finally get it, the antora.yml acts like a Tag or reference so that pathnames (absolute or relative) are not needed. What you absolutely must use is the antora name key: field.

rgleason commented 3 years ago

manuals\plugins\modules\antora.yml contains "name"opencpn-manuals"

This is just wrong it is "name: opencpn-plugins" Making the appropriate changes to

sources\antora.yml now has nav: - xref:opencpn-manuals:ROOT:nav.doc and it still does not work.

rgleason commented 3 years ago

In sources\antora.yml and sources\<plugin>\manual\antora.yml

I've tried

nav:
 - xref:opencpn-plugins:plugins:modules:ROOT:nav.adoc

and

nav:
 - xref:opencpn-plugins:modules:ROOT:nav.adoc

Starting to run out of ideas now. After a lot of reading I should be able to get the plugin documentation to show nav.doc in the left nav.

rgleason commented 3 years ago

I tried another version with two ":" after xref and that did not bring the nav.adoc into the left nav panel. BTW I think the component is "opencpn-plugins" and that "modules" is required, and that this is "ROOT" and "nav.adoc" is the file.

nav:
 - xref::opencpn-plugins:modules:ROOT:nav.adoc
rgleason commented 3 years ago

None of the plugins under sources have a sources\plugin-name_pi\manual\antora.yml with a nav: like nav:

nav:
 - xref:opencpn-plugins:modules:ROOT:nav.adoc

The component descriptor nav key

So what makes them render and use a Left Nav bar?
Can that be turned off?

rgleason commented 3 years ago

Found this about making conditional logic. https://gitlab.com/antora/antora/-/issues/332#note_111685811

rgleason commented 3 years ago

Found this about sorting content I'll give you one example that came from another Antora user. The user wanted to sort the components in the navigation. What we did was introduce a global site-component-order AsciiDoc attribute that controlled the order.

rgleason commented 3 years ago

Looking at the way the current system works for referencing sources\watchdog_pi ROOT\partials\nav-main.adoc has ** xref:watchdog::index.adoc[Watchdog] image:managed_plugin.png[]

Working back the other way to get to manuals:plugins:modules:ROOT:nav.adoc antora.yml for watchdog I think I should just have 

nav: 
- xref:modules:ROOT:nav.adoc[]

The component descriptor nav key

rgleason commented 3 years ago

No change, it is all just coming out of a can and not following the nav field.

Under keys I found cache_dir and fetch to refresh the cache but I don't think we are using this are we?

leamas commented 3 years ago

sources\antora.yml now has nav: - xref:opencpn-manuals:ROOT:nav.doc

This is the correct xref. The remaining part is that openpcn-plugins must be visible i. e., included in antora.yml. Is it?

rgleason commented 3 years ago

No I don't believe it is. What do I do? Add Include: opencpn-plugins in the same antora.yml?

rgleason commented 3 years ago

Include an example from another component

Alec, Is this the line I would need?

include::opencpn-plugins:modules:ROOT:nav.adoc

Component " watchdog"

In sources\watchdog_pi\manual\antora.yml antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav: 
- xref:opencpn-manuals:ROOT:nav.doc     (This might need to be - xref:opencpn-plugins:ROOT:nav.doc)
include::opencpn-plugins:modules:ROOT:nav.adoc

Component "opencpn-plugins"

There are two Antora files one at the top and one several directories down next to "modules" Also the first antora at the top, is this creating confusion by Antora?

name: opencpn-plugins
title: OpenCPN Manuals
version: '0.1'
start-page: manual/master-plugins
nav:
  - modules/ROOT/nav.adoc

Then manual\plugins\antora.yml next to "modules" (ROOT is next down)

name: opencpn-plugins
title: OpenCPN Manuals
version: '0.1'
start-page: manual/master-plugins
nav:
  - modules/ROOT/nav.adoc

Tried the watchdog antora in several alternatives, no success.

rgleason commented 3 years ago

The top antora.yml next to the main site.yml is unnecessary and not used (IMHO) So I have removed it with no known problems.. Leaving the identical one under manual\plugins\antora.yml which is next to "modules" and is where the antora manual says it should reside.

rgleason commented 3 years ago

Now with the following antora.yml files only

OM-plugins\manual\plugins\antora.yml

(next to "modules"

name: opencpn-plugins
title: OpenCPN Plugins
version: '0.1'
nav: 
- modules/ROOT/nav.adoc

OM-plugins\sources\watchdog_pi\manual\antora.yml

(next to "modules")

name: watchdog
title: Watchdog
version: '2.4.29'
include::opencpn-plugins:modules:ROOT:nav.adoc
nav: 
- xref:opencpn-plugins:ROOT:nav.doc

After selection from the resultant html of the "watchdog" plugin documentation the left nav bar remains the same.

 Tactics
    0.1
TideFinder
    0.1
TwoCan Plugin
    0.1
UKtides
    0.1
etc.
rgleason commented 3 years ago

Component Descriptor: antora.yml

associates the files in the standard directory structure with the specified component name and version (explicitly referred to as the component version, if you want to get technical). This assignment of component information decouples the source files from the repository and branches in which they’re stored.

This is where the problem resides I think

rgleason commented 3 years ago

Here is the exact thing that is happening to the current setup See Dan Allen's note 3 years ago about Possibility of a master nav.adoc when using multiple repositories documentations " and the notes that follow.

See what HollowBeam did and what the result was. (Same as our Plugin Manual.)

Then Dan Allen responds

But when I click on one docs, the wanted left navigation disappear:

It sounds to me like each repository is identifying as a separate component. If you want all the pages to have the same navigation, then they all have to be in the same component. (They can be in different repositories, but the antora.yml file must have the same name and version properties). Right now, navigation is tied to a component+version. In Antora 1.1, it will be possible to create a single unified nav for all components. But that will require changes in your UI. See #281 (closed).

rgleason commented 3 years ago

This problem apparently was solved with resolves #281 attach navigation to component version object to make it accessible from template https://gitlab.com/antora/antora/-/issues/281

Compose navigation files across components https://gitlab.com/antora/antora/-/issues/423

rgleason commented 3 years ago

Including Navigation Content https://gitlab.com/antora/antora/-/commit/65f486d77d7ba4450875d3ec008a5a8813605901

rgleason commented 3 years ago

I now believe that the "sources" directory and "sources\,plugin_name_pi" folders are out of bounds for the antora system and not recognized as "components" so they are handled differently than the antora documents state.

Additionally: When I change the watchdog_pi antora.yml file to be 

name: watchdog
title: Watchdog
version: '2.4.29'
include::opencpn-plugins:modules:ROOT:nav.adoc     (also tried using a single colon, same result)
nav: 
- xref:opencpn-plugins:ROOT:nav.doc

and try to build locally with antora site.yml

Rick@Dart MINGW64 ~/documents/github/watchdog_pi/manual (master)
$ antora site.yml
error: antora.yml has invalid syntax; can not read a block mapping entry; a multiline key may not be an implicit key at line 5, column 4:
    nav:
       ^ in C:\Users\Rick\documents\github\watchdog_pi\ (ref: master <worktree> | path: manual)
Add the --stacktrace option to see the cause.

When I change the antora.yml to be 

name: watchdog
title: Watchdog
version: '2.4.29'
nav: 
- xref:opencpn-plugins:ROOT:nav.doc

antora site.yml builds OK and works as HTML although the nav used is the same as before!

rgleason commented 3 years ago

When I git remote update origin when at my local github/OM-plugins and then rebase and restore and update sources, I find watchdog antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav: 
- xref:opencpn-plugins:ROOT:nav.doc

It also builds OK with antora site.yml with no errors, however the nav.adoc is not being referenced and the Left nav is showing stilll:

 Admiralty Tide Tables
    0.1
AIS RTLsdr USB
    0.1
ais_radar_display
    0.1
Autopilot Raymarine
    0.1
ETC
rgleason commented 3 years ago

So my conclusion is that neither sources or sources\watchdog_pi are legitimate "components due to the way sources is being handled outside of the antora "cache" system. I also wonder how this is able to work and pick up the plugins, except that antora is working partially due to the site.yml having the site information for each plugin.

I am puzzled how antora would even know to look under "sources" for these plugins, since it expects to find multiple git accounts.

rgleason commented 3 years ago

The answer is that the main site.yml uses "sources" for all the plugins. So the source-state.sh scripts are what restore update and save all the current commits for the distributed github plugins cloning them into the source directory.

It appears that if antora does not find a nav path in the antora.yml given, it just defaults to something that works, because watchdog_pi built and the Html worked even with the nav statement in place.

When running antora locally from OM-plugins It appears that antora is still not finding the target nav.adoc file listed in the antora..yml for watchdog_pi. Antora surely recognizes the name-key "opencpn-plugins" and the rest of it is also correct, so something is missing, or antora does not treat "sources" directories like the other directories under manual\plugins

Moving sources to be under manuaL\plugins would probably fix this problem (and I may try it) but the scripts would have to be modified too. and so would the partials|nav-all.adoc, nav-main.adoc and nav-beta.adoc files for the new xref paths.

rgleason commented 3 years ago

I think this reference in "Navigation Assembly" adequately describes what Antora does with

4. Component version selector (Site)

https://docs.antora.org/antora/2.3/navigation/#component-dropdown

Look carefully at the index in the illustration, this is exactly what is happening in "sources" where each PI Manual is stored with an antora.yml and site.yml file.

When your site has several components and/or component versions, Antora

  1. assembles an aggregated list of the components and their versions.
  2. This main menu of components and their component versions is the component version selector.
  3. Antora automatically lists the components in alphabetical order.
  4. Each component version is ordered from the greatest or latest.

The difference being that in our Plugin Manual setup, it is not in the "Component Dropdown at the top left" , but in the left index!