Many Broken Links - rgleason's

rgleason commented 3 years ago

It looks to me like many errors are in sean's plugin docs or ones I handle.

weather_routing:ROOT:weather_routing.adoc Line: 243 statusbar:ROOT:statusbar.adoc Line: 252 watchdog:ROOT:watchdog.adoc Line: 204 opencpn-master-plugins:squiddio:squiddio.adoc Line: 171 tactics:ROOT:tactics.adoc Line: 216 vdr:ROOT:vdr.adoc Line: 159 find-it:ROOT:find-it.adoc Line: 156 rotationctrl:ROOT:rotationctrl.adoc Line: 132 projections:ROOT:projections.adoc Line: 141 route_great_circle:ROOT:route_great_circle.adoc Line: 180 celestial_navigation:ROOT:celestial_navigation.adoc Line: 177 UPDATED - DONE dash-t:ROOT:dash-t.adoc Line: 150 rtlsdr:ROOT:rtlsdr.adoc Line: 102 pypilot:ROOT:pypilot.adoc Line: 264 weatherfax:ROOT:weatherfax.adoc Line: 234 climatology:ROOT:climatology.adoc Line: 240 polar:ROOT:polar.adoc Line: 222 chartscale:ROOT:chartscale.adoc Line: 135 ais_radar_display:ROOT:ais_radar_display.adoc Line: 96 logbook:ROOT:logbook.adoc Line: 153 sweep_plot:ROOT:sweep_plot.adoc Line: 219

rgleason commented 3 years ago

I guess I would start with watchdog. From checklink log these two files don't exist. I need to find and add them.

file:///opencpn/manual/plugins/watchdog/s-wdpi-58.png     Line: 2286
Code: 404 File `/opencpn/manual/plugins/watchdog/s-wdpi-58.png' does not exist

file:///home/mk/src/opencpn-manuals/plugins/docs/watchdog/2.4.29/_images/wdpi-gz-007.jpg      Line: 2000
  Code: 404 File `/home/mk/src/opencpn-manuals/plugins/docs/watchdog/2.4.29/_images/wdpi-gz-007.jpg' does not exist

However there is no local html "docs" file yet. How to create? and this link shows no way to see html for my plugins yet. It would be helpful. https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/plugins.html#statusbar:ROOT:statusbar.adoc

rgleason commented 3 years ago

How would I run from bash prompt, a linkchecker or checklink on

C:\Users\Rick\Documents\GitHub\watchdog_pi\manual\watchdog\modules\ROOT\pages\watchdog.adoc

leamas commented 3 years ago

You need to make a local build. See https://github.com/opencpn-manuals/main/discussions/12#discussioncomment-1199028

leamas commented 3 years ago

From checklink log these two files don't exist. I need to find and add them

$ find . -name s-wdpi-58.png
./docs/watchdog/2.4.29/_images/s-wdpi-58.png
./sources/watchdog_pi/manual/public/watchdog/2.4.29/_images/s-wdpi-58.png
./sources/watchdog_pi/manual/watchdog/modules/ROOT/images/s-wdpi-58.png

I. e., they are there, but somehow the paths are wrong

leamas commented 3 years ago

The jpeg file is a little different:

$ find . -name wdpi-gz-007.jpg
$

But:

$  find . -name wdpi-gz-007.jpeg
./docs/watchdog/2.4.29/_images/wdpi-gz-007.jpeg
./sources/watchdog_pi/manual/public/watchdog/2.4.29/_images/wdpi-gz-007.jpeg
./sources/watchdog_pi/manual/watchdog/modules/ROOT/images/wdpi-gz-007.jpeg

That is , the file exists but is .jpeg, not jpg. For some reason this is common.

rgleason commented 3 years ago

Alec, that is helpful process. Thanks. Would I make the correct link changes in my local repository for this and then push? Do I run antora in some special way?

Found this html from rasbats repos https://rasbats.github.io/opencpn-plugins-manual/opencpn-master-plugins/0.1/plugins.html but I probably shouldn't use that.

leamas commented 3 years ago

Would I make the correct link changes in my local repository for this and then push?

Yes

Do I run antora in some special way?

It depends. If you are running locally, in your plugin, it's just antora site.yml which creates a docs/ directory, notably docs/index.html which is the watchdog manual.

If you want to rebuild the complete plugins manual you need to pick your changes (they must of course be pushed first)

$ cd whereever/plugins
$ ./source-state.sh update
$ antora site.yml

And that's it. The result is, as usual, in docs/ and docs/index.html

Rasbats commented 3 years ago

Rick ... make the changes in your local repo.

This is the reference. https://docs.asciidoctor.org/asciidoc/latest/macros/images/

Is using VS Code with the asciidoc extension open the manual folder from your repo. The preview will show the same errors as firefox.

leamas commented 3 years ago

If you want to install linkchecker and checklink on Windows they are on Pypi and CPAN. I think it's possible to install these tools on windows, but...

rgleason commented 3 years ago

@leamas @rasbats Thanks for the guidance.

Should I clone the entire opencpn-manuals like Alec seems to have? Currently just cloned "development" How big is it? -Old laptop getting full. When we get the new ones setup I'll have more space.

file:///home/mk/src/opencpn-manuals/plugins/docs/watchdog/2.4.29/_images/wdpi-gz-007.jpg Line: 2000

I also wonder about the version number in there. How is that handled with my local which does not have it?

Also when we convert over to using this Plugins manual, I think there will be some additional link changes in every plugin.

leamas commented 3 years ago

Should I clone the entire opencpn-manuals like Alec seems to have?

No need if you just want to work with watchdog. The complete things is only required when rebuilding the complete manual.

Rasbats commented 3 years ago

Ref wdpi-gz-007.jpg you will probably find wdpi-gz-007.jpeg in the images folder (or vice-versa)

And helps to get rid of "Back to top of page" links in the body and the references to them at the top of the page.

Off to collect a lot of cut grass before it rains.

rgleason commented 3 years ago

using VS Code with the asciidoc extension open the manual folder from your repo. The preview will show the same errors as firefox.

It did not know about that... https://docs.asciidoctor.org/asciidoctor/latest/tooling/#visual-studio-code

leamas commented 3 years ago

... actually, you cannot change anything in watchdog after cloning the complete manual, the copy here is more or less read-only. The only sensible way to change things is to work with the plugin.

rgleason commented 3 years ago

OK, will work that way. Much preferred! What about the version numbers that I see? Should I change my local accordingly?

k/src/opencpn-manuals/plugins/docs/watchdog/2.4.29/_images/

how does that work?

leamas commented 3 years ago

We have not discussed versioning of the manual, so I suggest to just leave it as it is for now.

rgleason commented 3 years ago

@leamas Ok, I will ignore this question for the time being and not worry about it.

@Rasbats Should I be using https://code.visualstudio.com/docs
to be able to use
https://docs.asciidoctor.org/asciidoctor/latest/tooling/#visual-studio-code https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode That looks like a good tool set to use for Windows.. Is it your preferred way?

Rasbats commented 3 years ago

That looks like a good tool set to use for Windows.. Is it your preferred way?

Yes.

Rasbats commented 3 years ago

Rick ... Just be aware that in VS Code a link may seem to work in preview. Worth having a look at Firefox to check.

rgleason commented 3 years ago

Have installed VS Code and added site.yml. but don't know what to put in for the URL?

Next I need to install [AsciiDoc for VS Code](site:

site:
  title: Watchdog_pi Manual
  url:  https://nowhere.net    <--- What here?
  start_page: watchdog:ROOT:watchdog.adoc
content:
  sources:
    - url: ../..
      start_path: manual/watchdog/
      branches: HEAD
      edit_url: true
ui:   
  bundle:
    url: https://gitlab.com/leamas/antora-ui-default/-/raw/master/latest/ui-bundle.zip
    snapshot: true
output:
  dir: ./docs
  clean: true

rgleason commented 3 years ago

in VS Code hit control-p to open Quick Open Dialog and in the popup paste in with ctrl-V

ext install asciidoctor.asciidoctor-vscode

leamas commented 3 years ago

YOu can leave at as it is. It's required, but not used.

rgleason commented 3 years ago

I can leave site.yml line url: https://nowhere.net as is, required but not used.

Ok, now what? When I run "antora site.yml"

Rick@Dart MINGW64 ~/documents/github/watchdog_pi (master)
$ antora site.yml
error: playbook file not found at C:\Users\Rick\documents\github\watchdog_pi\site.yml (path: site.yml, cwd: C:\Users\Rick\documents\github\watchdog_pi)
Add the --stacktrace option to see the cause.

I put site.yml here where the other yml are:

C:\Users\Rick\Documents\GitHub\watchdog_pi\manual\site.yml

rgleason commented 3 years ago

I have playbook.yml in the same folder location

site:
  title: Watchdog Manual
  url: https://localhost:8080
  start_page: watchdog::watchdog.adoc

content:
  sources:
  - url: ./
    start_path: watchdog
    branches: HEAD

ui:
  bundle:
    url: ./ui-bundle.zip
    snapshot: true

output:
  clean: true
  dir: public

leamas commented 3 years ago

wrong directory. YOu are in watchdog, but site.ytml is in watchdog/manual. Go there, and antora will look in the right place.

rgleason commented 3 years ago

Ok, change directories to be in Manual I think using bldloc.yml works and creates a .public directory under manual.

Rick@Dart MINGW64 ~/documents/github/watchdog_pi (master)
$ cd manual

Rick@Dart MINGW64 ~/documents/github/watchdog_pi/manual (master)
$ antora bldloc.yml

Rick@Dart MINGW64 ~/documents/github/watchdog_pi/manual (master)
error: Local content source must be a git repository: C:\Users\Rick\documents\github (url: ../..)
Add the --stacktrace option to see the cause.

bldloc.yml File

site:
  title: Watchdog Manual
  url: https://localhost:8080
  start_page:  watchdog::watchdog.adoc

content:
  sources:
    - url: ./
      start_path: watchdog
      branches: HEAD
      edit_url: true
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
output:
  dir: ./public

What should I do to fix site.yml?

leamas commented 3 years ago

sources | url should be .. not ./

rgleason commented 3 years ago

Ok will change and try site.yml again. Using the output of bldloc.yml found in .public and browsing to watchdog/manual/.public/index.html I see

rgleason commented 3 years ago

The original untouched site.yml is (and remains so) with -url: ../.. and it does not work. The bldloc.yml above has sources: - url: ./ and it works.

site:
  title: Watchdog_pi Manual
  url:  https://nowhere.net    <--- What here?
  start_page: watchdog:ROOT:watchdog.adoc
content:
  sources:
    - url: ../..
      start_path: manual/watchdog/
      branches: HEAD
      edit_url: true
ui:   
  bundle:
    url: https://gitlab.com/leamas/antora-ui-default/-/raw/master/latest/ui-bundle.zip
    snapshot: true
output:
  dir: ./docs
  clean: true

rgleason commented 3 years ago

I think I should standardize on a site.yml that works that we are all using (and use it from the same directory as you both are doing)

leamas commented 3 years ago

It's not possible, there are always names which need to be configure. Please push your current state and report back where I can find it.

rgleason commented 3 years ago

Alec, when I change -url: ../.. to -url: ../ antora site.yml does build and creates a new docs/ directory with index.html

content:
  sources:
    - url: ../
      start_path: manual/watchdog/
      branches: HEAD
      edit_url: true

and opening the index html it looks much the same.

So now I have two questions How do I run link checker or check link locally, the easiest way? I think I can edit files with VS Code or with my favorite Notepad ++

In VS Code not quite sure how I run the Asciidoc Extension.... which is installed. I think I can learn from this https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode

Rasbats commented 3 years ago

how I run the Asciidoc Extension.... which is installed.

This is used for the preview. Ctrl-Shift-v opens the preview page.

leamas commented 3 years ago

Linkchecker us available in pypi, and checklink in CPAN. Using these on windows is unchartered territory for me. If you are satisfied with your changes I suggest the following

You talk to Mike
Mike includes your plugin in the overall manual
Mike make a push to the build branch. This will run all checks. You can then fix, commit and push.
The first times you will probably ask Mike or me to make a new test build. But over time, you will learn this, it's not that complicated once the plugin is included.

@Rasbats ^

rgleason commented 3 years ago

@Rasbats Mike how do you linkcheck for these.. easiest way found? @leamas Thanks for the overall process...Don't know why the -url: path is different for various people, setups, but that is not of consequence...

leamas commented 3 years ago

how do you linkcheck for these.. easiest way found?

The easy way is to push to build branch. This runs alls checks automatically, you can see the results under the Actions button

leamas commented 3 years ago

Frankly, handling pypi and cpan on windows i. e., install linkchecker and checklink is probably not easy if you are not used to these tools.

leamas commented 3 years ago

@rgleason Are you working with watchdog? if so, what's the url? https://github.com/rgleason/watchdog, or something else?

rgleason commented 3 years ago

https://github.com/rgleason/watchdog_pi Master branch.

I have installed a Firefox extension called "Broken Link Checker" which works fine. I believe have fixed all the links now on my local, so now I git add, git commit and git push ?

Or do I run a check with some special commands? I could find those I think.....

leamas commented 3 years ago

I have included https://github.com/rgleason/watchdog_pi.git in the plugins manual and pushed to build branch. Results are under way if you check https://github.com/opencpn-manuals/plugins/actions/runs/1147905235, that is the Actions button in https://github.com/opencpn-manuals/plugins. It takes about 5-6 minutes, most of the time is the full linkcheck.

leamas commented 3 years ago

First of all: push your changes.

leamas commented 3 years ago

Do it now. As soon as your changes are visible we can check them, but not before.

leamas commented 3 years ago

Results from earlier version at https://textbin.net/8vni7jtdah

Rasbats commented 3 years ago

Are the sources not needing adding again in site.yml and the comments deleted from the adocs? This to get the checks carried out?

leamas commented 3 years ago

Yes. I have done it in my opencpn-plugins repo, but not pushed. Doing that now, and leaving scene for a while

rgleason commented 3 years ago

Had to use

Rick@Dart MINGW64 ~/documents/github/watchdog_pi (master)
$ git remote set-url origin git@github.com:rgleason/watchdog_pi.git

Then the commit was pushed.

Rasbats commented 3 years ago

pulled from plugins/main and I can see the added source.

rgleason commented 3 years ago

Good..
This link is flagged as dangerous by Norton and I am not allowed to use it https://textbin.net/8vni7jtdah

rgleason commented 3 years ago

That commit included the "docs" directory. Is that correct? https://github.com/rgleason/watchdog_pi/tree/master/manual/docs

or should it be ".docs" and be hidden from commits?

Rasbats commented 3 years ago

public and docs should be added to .gitignore.

opencpn-manuals / plugins

Many Broken Links - rgleason's #8