Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
    David Jencks
    @djencks_gitlab
    So when viewing the site no reference to https://testnet.lisk.io/api/spec occurs?
    Mona Bärenfänger
    @Tschakki

    Yes, it transforms the content of https://testnet.lisk.io/api/spec dynamically. As I mentioned, this works perfect if I run gulp preview.

    So the issue is not swagger related. It’s just the general question how to add an additional page to Antora UI that is NOT based on .adoc

    David Jencks
    @djencks_gitlab
    Perhaps I'm nitpicking, but Antora doesn't have pages, your site does. And normally the UI doesn't have pages either, it has layouts.
    Mona Bärenfänger
    @Tschakki
    Hmmm maybe we get closer? Is there any documentation about the concept of these layouts? That might help me
    David Jencks
    @djencks_gitlab
    Most of the docs I've found about layouts is at the handlebars site. However, if it works in preview but not when you generate your site that suggests that your modifications aren't getting into the UI bundle you are using to generate your site, which is an easier problem :-)
    Mona Bärenfänger
    @Tschakki
    Oh no, I think they get into the UI bundle. But The thing is it fails ^^
    David Jencks
    @djencks_gitlab
    Have you checked "by hand" that your changes are actually in the UI bundle Antora is actually using?
    Mona Bärenfänger
    @Tschakki
    Error: default layout not foundis the error
    I will look at the handlebar docs and see if they can help me...
    thanks for your help so far!
    David Jencks
    @djencks_gitlab
    they won't help, you've broken something else....
    did you set the default layout in the playbook or is it still "default"?
    Mona Bärenfänger
    @Tschakki
    as I said I did it the hacky way. I truely believe there is a more simple way, I just don’t know it, and sadly it’s not documented for Antora UI
    I did not set the default layout in playbook, so it should be default
    David Jencks
    @djencks_gitlab
    Is the gitlab URL you showed your actual UI you are using?
    Mona Bärenfänger
    @Tschakki
    Github you mean? Then yes :)
    This is branch with site.yml: https://github.com/LiskHQ/lisk-docs/blob/build/site.yml
    This is the UI: https://github.com/LiskHQ/lisk-docs/tree/antora
    David Jencks
    @djencks_gitlab
    I don't see anything wrong yet, but the error you get suggests that the UI bundle that Antora is trying to use has major problems, and that that default layout .hbs is not in the expected location. I would compare your built UI bundle with a downloaded Antora default UI bundle and check that everything seems to be in the right place.
    Mona Bärenfänger
    @Tschakki
    Ok thanks, I will double check :)
    This is btw the commit where I tried to included swagger-ui: LiskHQ/lisk-docs@44e1e65
    You can see there I needed to edit the file build-preview-pages.js to make it work. My guess is that a different file is used during the build and this is why it fails
    David Jencks
    @djencks_gitlab

    I think you have two problems:

    • your UI is broken somehow so that not even the default layout is found by Antora
    • I think there's also a conceptual problem in that layouts are only used to "decorate" or lay out actual pages generated by Antora. I don't think you will be able to end up with a page using the swagger layout unless that page is known to Antora. Your change to build-preview-pages.js sidesteps this.

    Normally you specify the layout as a page attribute :page-layout: swagger I think you can have a page with just a top level title and that attribute. I would suggest also including the URL used by your js code as a page attribute :page-swagger-url: https://testnet.lisk.io/api/spec, you can reference it in the .hbs with {{page.attributes.swagger-url}}

    You could also consider writing an asciidoctor extension to generate the page statically at build time, so the site doesn't need to access that URL.

    Mona Bärenfänger
    @Tschakki
    Thank you @djencks_gitlab ! This was really useful help :) I will follow your suggestions and try it this way :+1:
    David Jencks
    @djencks_gitlab
    If, as I think, your page needs to be generated by Antora, your link to it in the header might be tricky (I'm not sure at all). The version of Antora under development (2.3.0) has some enhancements to make more information available to the UI. Ideally you'd use an xref in the header to link to your page, and that might only work with the development version. I'm just not sure.
    Including external content in an Antora site is a big open topic, for instance java based projects usually would like javadoc. It's very tricky to do right which is why there isn't good support yet.
    good luck and let us know what happens!
    Mona Bärenfänger
    @Tschakki
    :+1:
    Mona Bärenfänger
    @Tschakki
    I agree it is useful and needed to have some parts of the docs auto generated with e.g. JavaDoc from the code. We plan to do this as well with TypeDoc (we want to use it for documenting the technical reference of certain parts of the software) Also API documentation is better auto-generated, this is why we use swagger (where you can explore the API interactively through the UI additionally)
    Mona Bärenfänger
    @Tschakki
    Hey, quick update: The way @djencks_gitlab described it works :) I Added an empty .adoc file with just title and :page-layout: swagger and as I added this layout to UI before, it immediately worked: https://liskhq.github.io/lisk-docs/lisk-core/api.html#/Accounts/getAccounts :D
    KLynn2019
    @KLynn2019
    Hi all...quick question: Is it possible to point to attachments that are stored in an attachments folder that's not in the same module where the link is being created? Antora documentation and my tests up to this point suggest no but maybe I'm misreading/doing it wrong.
    What I'd like to do: Store PDFs as attachments in the same repository that contains other shared content. Multiple sites access these files so it would be nice to have them all in one location.
    What I'm trying not to do: Have individual PDFs in a separate standalone location on our docs server. It's not the end of the world, but it would be one more thing for the site admin (who's not on the writing team) to worry about.
    David Jencks
    @djencks_gitlab
    @Tschakki excellent! However, for me the links in the header don't work, do they for you?
    @KLynn2019 do you mean separate component? What have you tried that doesn't work?
    Mona Bärenfänger
    @Tschakki
    No, the above link is still broken, I haven’t worked on this yet. I will let you know if I fix it @djencks_gitlab - but if I can’t, maybe I just hardcode the correct link for now ;)
    David Jencks
    @djencks_gitlab
    My suspicion is that you will either need to hardcode the link or use some new features in 2.3.0 which I'm not even sure are merged into master yet. Dan has been adding some ways for the UI to use the content catalog. I think you'd need to call a method on the content catalog to get the location of your linked page from antora coordinates. However, I'm not at all sure about this.
    Ewan Edwards
    @eskwayrd
    @Tschakki If your Swagger HTML is built separately from Antora, you can copy it into the path where Antora generates its HTML (specified in the playbook as the dir field under output). Then, all you'd need to do is add a link in your UI to that page, doing something like <a href="{{uiRootPath}}/../path/to/swagger.html">Swagger</a>. Specifically, if your Antora-generated HTML is in a folder called build, and you place swagger.html at the root of build, then that link would be <a href="{{uiRootPath}}/../swagger.html">Swagger</a>.
    David Jencks
    @djencks_gitlab
    @eskwayrd won't that show the swagger page(s) as-is? @Tschakki wants them to be "decorated" by antora using a particular layout.
    Ewan Edwards
    @eskwayrd
    Yes. If you want API pages decorated like any other pages, I'd suggest converting the Swagger-collected API details into Asciidoc markup, and then those generated pages are just like any other page that you author. See: https://phauer.com/2017/rest-api-documentation-swagger-asciidoc/
    David Jencks
    @djencks_gitlab
    @KLynn2019 I would try figuring out where the attachments will end up in your generated site and defining your own property, globally, pointing to it. e.g. commonAttachmentsDir: /shared/1.0/attachments and link:{commonAttachmentsDir}/foo/bar/my.pdf I have no idea if this will actually work though...
    Ewan Edwards
    @eskwayrd
    I used this approach when I last incorporated Swagger API content into my doc content, but I was using PHP for the implementation (at the time).
    Mona Bärenfänger
    @Tschakki
    @eskwayrd thanks, but I do not want to convert to asciidoc format, as this would loose the possibility to make interactive requests to the server. The solution I have now thanks to @djencks_gitlab seems like a good way to go for me :)
    Ewan Edwards
    @eskwayrd
    :ok_hand:
    The interactive part of Swagger was relatively easy to separate from the presentation part of Swagger, since the latter could be used server-side and the former runs in the browser. If you translate to Asciidoc format, you can still use the interactive bits, but you have to do a bit of work to make that happen.
    That said, I'm not currently using Swagger, so I don't have a working implementation to reference.
    David Jencks
    @djencks_gitlab
    @eskwayrd I don't have any rest to document, but I like that approach! I'm a bit curious... in java the term swagger seems to have been generally replaced by openapi. Have they diverged?
    Ewan Edwards
    @eskwayrd
    https://swagger.io/docs/specification/about/
    Looks like the Swagger spec became the OpenAPI spec, and that Swagger is now "just" one tool that uses it instead of the only tool. When I last used Swagger, it was before OpenAPI existed (nearly 5 years ago).
    KLynn2019
    @KLynn2019
    @djencks_gitlab Yes, I mean separate component. I have one that contains content that's used by multiple sites. That's where I'd like to store the PDFs.
    Per the Antora documentation, I didn't specify an explicit attributes location. I just used {attributesdir}.
    Originally I tried specifying the component and module: link:Shared:Settings:{attributesdir}/Setting.pdf[link text]
    When that didn't work, I tried specifying a different module in the app-specific component: link:Settings:{attributesdir}/Setting.pdf[link text]
    When THAT didn't work, I went ahead and put the PDF in an attributes folder in the module with the link: link:{attributesdir}/Setting.pdf[link text]
    In all cases, Antora created an _attributes folder with the PDF in it, but in no case did clicking on a link display a PDF. In the latter case (attribute in same module as link), I got a "file not found" message even though I could see the PDF in the correct folder.
    Ewan Edwards
    @eskwayrd
    @KLynn2019 The link macro doesn't understand Antora's component ids as used in the xref macro. I think that this is the relevant issue: antora/antora#180
    One suggestion, which is a hack to be sure, would be to place all of the PDFs in one module, and then in other modules, create a symbolic link to the PDFs in the first module, making specific PDFs available to the current module without incurring additional file storage. If your authoring/publishing infrastructure is all on Posix-compatible file systems (ie, not on Windows) this could work well. If you're on Windows, your mileage may vary. :-)
    Ewan Edwards
    @eskwayrd
    Another suggestion would be to host the PDFs independently from Antora. Say in an AWS S3 bucket. Then everywhere that needs to use them just links to the file structure in that hosting.
    KLynn2019
    @KLynn2019
    @eskwayrd Your latter suggestion is probably what's going to happen except they will be on our docs server. I was just trying to sidestep that so that the writing team would have more control over where that content exists (again, ideally in a component accessed via Antora).
    We are a Windows shop...for better or worse. :) It's not clear to me where the symlink would be created or how it would be used by the writers who will be taking over this data once I finish with it.
    Ewan Edwards
    @eskwayrd
    @KLynn2019 Fair comments.
    There can be undesirable side effects of using symlinks, especially with varying support across platforms.
    While I understand the desire for authors to have one way to manage things, PDFs tend to be an exception for a text-based file workflow. Since they tend to be notable larger than the Asciidoc files around them, and because they are an opaque format that is hard for versioning systems, like Git, to reason about, adding them to your repos, especially if you have large numbers of PDFs, tends to be an idea that you outgrow fairly quickly.
    The solution tends to be whatever works for your team's skillset, your budget, and operational capabilities. For example, some teams that I've worked with serve all of their regularly updating, large binary assets in a shared Dropbox folder, and their web pages simply link to those.
    KLynn2019
    @KLynn2019
    @eskwayrd Thank you for your perspective. Much appreciated!
    The PDFs range from 35-60K in size but compared to the Asciidoc files, they are quite large, and in certain sites there would be a lot of them. I will see if I can get the site admin to put these into a single location so that at least they're easy for writers to reference from within the Asciidoc files.