Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
    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.
    Jared Morgan
    @jaredmorgs
    @djencks_gitlab @gmarpons I’ve got the basic system working again after realising I wasn’t supporting the correct build branch in my site.yml. I’m going to record a demo of the solution at the current state, before I begin messing with the global version variables that @gmarpons suggested.
    I’ll share it here for reference once it’s upload to youtube
    Joseph Cayouette
    @jcayouette
    Is there a way to setup CI to build PR branches automatically for viewing?
    Andreas Schilling
    @styx_hcr_twitter
    I remember some discussion, but there's no ready-to-use process or even "technology" to do so.
    due to the distributed nature it's obviously not very straight-forward
    we're also thinking about possible solutions, but have not dived in very deep yet
    Joseph Cayouette
    @jcayouette
    Right its pretty challenging
    Andreas Schilling
    @styx_hcr_twitter
    a naive approach would be to have specialized site-pr.ymlfiles within the master documentation build project, but the bigger issue is, that PRs usually would be triggered from "downstream" projects where the actual content lies, potentially even from multiple ones.
    so, in the end it also depends to some extend on the used infrastructure (e.g. Jenkins) and whether it is possible to define such relations and trigger respective build actions
    Joseph Cayouette
    @jcayouette
    @styx_hcr_twitter Thank you. Ill have a look at this an see how we can hack a prototype together
    Mona Bärenfänger
    @Tschakki
    @djencks_gitlab I hardcoded the link in the top nav now. :) Changes are now live: https://lisk.io/documentation/lisk-core/api.html
    thanks again for the help :)
    Guillem Marpons
    @gmarpons

    @gmarpons I didn’t consider that perhaps the reason why the solution you proposed isn’t working for me is because of a version incompatibility. We are currently still running Antora 2.0

    @jaredmorgs Yes, I think you need at least version 2.1. The functionality added in this issue is relevant to my experiment: antora/antora#430.

    Aonghus O'Lochlainn
    @olochlainn
    Hi, I have been asked at short notice to set up a separate additional component, where is this covered in the docs (can't see it) and is there a sample website with multiple components?
    Aonghus O'Lochlainn
    @olochlainn
    I've only done a single component previously and am not sure hwo to proceed
    Aonghus O'Lochlainn
    @olochlainn
    Actually have started to get it working now, panic over. Any pointers to info in docs welcome though.
    One question - if antora.yml specifies a component, if I want my second component to use exactly the same content that is in one module (say) of my first component, do I have to create a new branch in that repo with the same exact content? What is the best approach?
    Andreas Schilling
    @styx_hcr_twitter
    what would be the use case for this, just to understand?
    Aonghus O'Lochlainn
    @olochlainn
    We have a platform user guide and then a separate user guide for an important sub-component of the platform
    So maybe 10 repos for the platform user guide, including one that is used solely for that sub-compoment
    Also, separate question re UI, is there any way to force the little drawer at bottom left to show my two available components rather than one, forcing user to click down arrow to see the other component?
    Andreas Schilling
    @styx_hcr_twitter
    I don't think including (not just linking) content from other components is possible, but I might be wrong. Still, if it's just a sub-component (in the software sense), wouldn't it be appropriate to just have it as a separate module and subchapter in the navigation?
    Then again, you know your stuff and probably have reasons :)
    Aonghus O'Lochlainn
    @olochlainn
    There's an important distinction between the subjects (basically backend vs frontend) so they want to have two distinct presentations. I actually have it working, just needing a separate branch on repo, I will leave it to the GitHub gurus here to agonize over the repo details :-)
    David Jencks
    @djencks_gitlab
    @olochlainn There are a lot of examples of multiple components in my simple examples project and there are schematics to create a new component or create a project with multiple components in my antora-schematics project.
    https://gitlab.com/djencks/simple-examples
    https://gitlab.com/djencks/antora-schematics
    One of the simple-examples shows how you can copy content from one component to another using page stubs.
    David Jencks
    @djencks_gitlab
    @styx_hcr_twitter Indeed you can include content from any component in any other component. There's an example at multiple-components/shared-content-xrefs in my simple-examples project.
    Ewan Edwards
    @eskwayrd
    @jcayouette I use Netlify to build+host my docs. They make it dead simple to have PR-specific builds of my docs, triggering on each commit. In the past, I've used Travis CI, Circle CI, buddybuild, Jenkins. All of those take some effort, from sorta simple to sometime extreme effort. Netlify takes a few clicks. You're rolling in under a minute, and it just works.
    The only gotcha is that they optimize for pulling master (or the specified branch) only. If your Antora setup is a "local" repo that involves multiple branches for doc content, you need to run a script that performs a full clone.
    Jared Morgan
    @jaredmorgs
    @gmarpons thanks for confirming. I’ll have to insist we upgrade Antora to 2.2 sooner rather than later.
    Ewan Edwards
    @eskwayrd
    @jaredmorgs It should be a drop-in replacement. One thing that you can do to make sure that it's the same is to compare the output before and after the upgrade, say using diff. You should only see differences in the "generator" meta tags for the HTML files (the sitemaps will have new timestamps).
    Chris Cranford
    @Naros
    Hi guys, hopefully a quick question. Generally we've be placing our asciidoc variables/attributes in _attributes.adoc, but is there a way to instruct Antora to globally include that file or its contents as a part of building each page without explicitly doing so in the various .adoc files themselves?
    Ewan Edwards
    @eskwayrd
    You can define global attributes in your playbook file:
    asciidoc:
  attributes:
    foo: bar
    David Jencks
    @djencks_gitlab
    Or, now, in an antora.yml file.