Orchid Starter Guide isn't very beginner friendly.

[Andre601]

I want to try out Orchid on my multi-module project, but it does nothing more than generating the default pages that you get when trying out the Java-example.

I already tried to create a config.yml in the main src/main/resources directory but it didn't work. Putting it directly into the root directory also didn't change anything.

I am aware that the gitter chat is your (prefered) way of giving support, but as of writing this issue is noone active there and my personal guess is, that I won't be online when I receive an answer, making support delayed and unpleasant.
If there is any other form of comunication, such as a Discord chat or similar would I really appreciate to get forwarded to it.

My main issue is - as described above - is that the config seems to get fully ignored.
I'm in the process of turning my single-module project into a multi-module one and therefore use the multi module setup for the config.

But no matter if I put the config file in src/main/resources, just the root directory or in a dedicated docs module does Orchid do absolutely nothing with the projects module setup.

My config.yml currently looks like this:

javadoc:
  modules:
  - name: 'JavaBotBlockAPI (Core)'
    slug: 'javabotblockapi-core'
    sourceDirs: ['../core/src/main/java']
  - name: 'JavaBotBlockAPI (JDA-Module)'
    slug: 'javabotblockapi-jda'
    sourceDirs: ['../jda-module/src/main/java']
    relatedModules: ['JavaBotBlockAPI (Core)', 'JavaBotBlockAPI (Request-Module)']
  - name: 'JavaBotBlockAPI (Request-Module)'
    slug: 'javabotblockapi-request'
    sourceDirs: ['../request-module/src/main/java']

I of course added the javadoc plugin as a orchidRuntime dependency to the source build.gradle.

I'm frustrated beyond any belief and close to just throwing this entire thing away.

[cjbrooks12]

I apologize for the delay on Gitter. I just moved and have not been online much in the past few weeks.

There are a few things to check:

1. Orchid should be in a separate subproject from the other modules
2. config.yml should be in src/orchid/resources of its module (not src/main/resources)
3. The paths linked to in sourceDirs are relative to the config.yml. To check you have the right paths, you can cd into src/orchid/resources and ls your way through parent directories to get to the right source directories

[Andre601]

1. Orchid should be in a separate repo from the other modules
2. config.yml should be in src/orchid/resources of its module (not src/main/resources)
3. The paths linked to in sourceDirs are relative to the config.yml. To check you have the right paths, you can cd into src/orchid/resources and ls your way through parent directories to get to the right source directories

1. By "separate repo" you mean a separate module (like the docs module that was suggested in the kotlin setup guide)?
2. This is poorly explained in the guide as it (at most) mentions that it has to be in src/orchid/resources (Just found it a few seconds before your reply) but not if this directory has to be in its own module/directory, or if it has to be as a part of the root project itself.

[cjbrooks12]

Yes, I meant separate subproject, I've corrected the comment above.

And this tutorial was written to be read top-down slowly and carefully, as it is a literal step-by-step guide, not as a quick reference. The Homepage subheader is the first time it mentions adding Orchid-specific files to the site, and I tried to be pretty clear about which directory these files need to be in:

The first thing anyone will see when landing on your site is your Homepage. Orchid creates this page based on a homepage.md file in the root of your site's resources, which are located by default in src/orchid/resources.

Additionally, every code snippet in that tutorial includes the full path of that file in the project as the first line of the snippet, so they all include src/orchid/resources, not src/main/resources. I tried to be as clear as I could about the locations of all files for using Orchid, but if you have suggestions about how to make it more clear, I would appreciate the tips so I can get it corrected!

[Andre601]

Maybe adding a small section called default/source locations or something alike to the Your first orchid Site may be an idea, to inform right from the beginning, that Orchid-related files are stored in a specific direction (and that you can alter it if so desired).

It's a small change, but sure wouldn't hurt.

About my issue: I got the Orchid plugin now to find the sources for Javadoc, but I now face the issue, where it can't find pages?
I essentially want Orchid to link to other modules, if I have a {@link path} tag in the comments pointing to a different modules.
If I understand it correctly do I have to set relatedModules as an option in the config, to enable this?
When I do this, do I set this setting on the modules that link TO the specified module, or in the module, that I will link to?
Also, when I define a slug, is that one used over the name in the relatedModules, or is just the name used?

Because I receive a lot of errors like these here:

[ERROR]     - Error creating anchor to [collectionType=javadoc, collectionId=JavaBotBlockAPI (Core), itemId=java.lang.Deprecated] from [http://localhost:8080/javadoc/javabotblockapi-core/org/botblock/javabotblockapi/core/annotations]: matching page not found

Edit: Looking over the errors does it seem to be a general issue with linking to external Java sources such as IOException
Is there a way to "tell" Orchid to use specific links to connect {@link} tags to external docs, similar to how the default Javadoc.exe can do this?

[cjbrooks12]

Orchid isn't able to link to stdlib classes or other sites' package-list files like normal Javadoc can, there's an open issue for this #237.

[Andre601]

Okay, thanks.
I assume there isn't any rough ETA on when this will become available?
Also, is there like any way to just "skip" those links for now?

[cjbrooks12]

No, I don't have an ETA on it yet, but it is one of the most requested features (along with #357). Those links are already being skipped, it will just print out the text (not as a link) instead. The errors are only shown in diagnose mode, so the site should still be building successfully

[Andre601]

The site does build, but it still only gives the default pages without any changes made at all.

To give some context, the current project structure is build like this:

:root
  |
  |- core # Core module
  |    |- src
  |        |- main
  |            |- java
  |                |- org.botblock.javabotblockapi.core # From here on are Java classes and other folders with classes.
  |
  |- jda-module # JDA module
  |    |- src
  |        |- main
  |            |- java
  |                |- org.botblock.javabotblockapi.jda # From here on are Java classes and other folders with classes.
  |
  |- request-module # Request module
  |    |- src
  |        |- main
  |            |- java
  |                |- org.botblock.javabotblockapi.requests # From here on are Java classes and other folders with classes.
  |
  |- src
      |- orchid
          |- resources
              |- config.yml # See below
              |-  homepage.md # Is also not rendered at all

And the config.yml, as of now is like this:

theme:
  primaryColor: '#2C2F33'

javadoc:
  modules:
  - name: 'JavaBotBlockAPI (Core)'
    slug: 'javabotblockapi-core'
    sourceDirs: ['../../../core/src/main/java']
  - name: 'JavaBotBlockAPI (JDA-Module)'
    slug: 'javabotblockapi-jda'
    sourceDirs: ['../../../jda-module/src/main/java']
    relatedModules: ['javabotblockapi-core', 'javabotblockapi-request']
  - name: 'JavaBotBlockAPI (Request-Module)'
    slug: 'javabotblockapi-request'
    sourceDirs: ['../../../request-module/src/main/java']

[cjbrooks12]

Could you push your work to another branch so I can take a look and see what's going on?

[Andre601]

The project is currently being remade to be a multi-module one.
It is currently worked on the release/6.0.0 branch, so you can use that one, as it also contains the Orchid attempts.
https://github.com/botblock/JavaBotBlockAPI/tree/release/6.0.0

[cjbrooks12]

Thanks, I'll take a look at it today

[Andre601]

I tried it the changes you PRed by executing gradlew :docs:orchidServe and while the command does work is the page still the exact same without any changes whatsoever.

Edit: The files seem to get generated, but somehow does the plugin not apply those to the live web-version?

[cjbrooks12]

What live web version? ./gradlew :docs:orchidServe is only a local dev server, and the site can only be viewed on localhost (just like any other SSG or documentation generator, really). You'd have to take that output and deploy it to your webserver manually (like you were probably doing with the current MkDocs site), or use ./gradlew :docs:orchidPublish to run one of Orchid's publishers once its configured

[Andre601]

I think I found the cause of the issue, but I need to investigate that.

My assumption is, that somehow a previous Gradle task (the orchidServe task) of the example project I tried out isn't shut down, so it probably runs in the background and overrides the default loclahost:8080 adress.
I will quickly try it with a separate port and if that is the case will attempt to locate and kill the other task.

[cjbrooks12]

You must have a terminal open somewhere, or a Gradle process is running in the background, or something else is being served on that port.

When you run orchidServe it will print out where the current site is being served.

But yes, if the default port is currently in use it will try to find another available port. Either view the site at the URL printed to the terminal, or try killing port 8080 and killing any running Java processes

[Andre601]

I can confirm that it was indeed a gradle daemon that was still running in the background and was somehow taking priority over the port. I killed it manually now and the docs are displayed as expected, although with some visual issues (see #385 as one of the issues. Another is, that syntax highlighing isn't working and that empty lines in code blocks are also missing.)

And orchid didn't try at all to use another port. It always printet the 8080 port in the console.
It seems like using Ctrl + C on a Git Bash terminal isn't really doing anything, so I killed the Gradle daemon with ./gradlew --stop

[Andre601]

What would be the easiest way to alter the background and text color in Orchid?
I essentially want to make it look like what the Dark Reader extension is doing but I'm fairly unsure what I would need to alter and where.
Especially since I'm not that good with CSS and especially SCSS

[Andre601]

I discovered something rather weird, which is, that links to normal classes from inside nested classes also don't seem to work?
Like the below image shows what is essentially the path to the BotBlock class. And this path is used inside the Builder class which is nested inside BotBlock (So it's BotBlock.Builder)

Can this somehow be fixed, considering that this is working for normal Javadoc generation?
This interestingly enough also seems to only happen for the return value description? Considering the main description has the same link working without issues.

(P.S. "Return Value" is missing a space)

[Andre601]

Next minor issue I found is again with the {@link} tag.

When you use {@link #method} to link to a method inside the same class is Orchid replacing this with the name of the main class and not with any provided text, even when you provided a text ({@link #method metho})

An example would be this line here which is changed to just PlannedRemoval

Could this perhaps be a bug/issue with annotation interfaces? Considering that those don't even seem to list the available fields and methods.