AsciiBinder is an AsciiDoc-based system for authoring and publishing closely related documentation sets from a single source.
Home Page: https://asciibinder.net
License: MIT License
Opening this on behalf of this thread.
I create a repo build it and then I run watch. And I always get this exception for any changes in
welcome/index.adoc. Any idea what I am doing wrong ?
asciibinder watch
10:24:41 - INFO - Using Guardfile at /home/nmajorov/.gem/ruby/gems/ascii_binder-0.1.9/Guardfile.
WARN: Unresolved specs during Gem::Specification.reset:
ffi (>= 0.5.0)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.
10:24:41 - INFO - LiveReload is waiting for a browser to connect.
10:24:41 - INFO - Guard is now watching at '/home/nmajorov/workspace/missions/Ringer/report/report_binder'
[1] guard(main)> 10:24:41 - INFO - Browser connected.
10:24:57 - ERROR - Problem with watch action!
> [#] undefined method `start_with?' for #<Pathname:welcome/index.adoc>
10:24:57 - ERROR - (eval):3:in `block (2 levels) in evaluate'
> [#] /home/nmajorov/.gem/ruby/gems/guard-2.14.1/lib/guard/watcher.rb:75:in `call_action'
> [#] /home/nmajorov/.gem/ruby/gems/guard-2.14.1/lib/guard/watcher.rb:44:in `block (2 levels) in match_files'
> [#] /home/nmajorov/.gem/ruby/gems/guard-2.14.1/lib/guard/watcher.rb:39:in `each'
> [#] /home/nmajorov/.gem/ruby/gems/guard-2.14.1/lib/guard/watcher.rb:39:in `block in match_files'
I believe we are stable enough that we an reduce the amount of default output to only list warnings and errors, not successful builds.
It would also be nice to have the "adoc files not in the topic map" error be optional.
This would help with CI/Cron.
If I create a directory of unpublished material called _foo can it get ignored for reporting unpublished files purposes?
We have an element syntax that contains things like
"ki" "do" and "on" with respective pages in the documentation called for example "do.adoc". When I try to add these to the topic configuration I get an error message on build saying it's not a string.
- Name: Do
File: do
I've tried and the minimum is 3 characters both for Name and File. Can I change this or is this a limit needed for something else?
Even if it's easy to install, it would be nice to have an docker image on dockerhub
I have _template/page.html.erb
it includes via <%= render("_templates/_footer.html.erb") %> a sub-template. That template can not use the images_path.
Is this a jinja limitation or something we can fix?
In the repo, it's just a symlink, but in the 0.1.5 release the symlink is broken. In manageiq_docs we have a rake task that runs using the ascii_binder symlink and that rake task is broken.
@nhr How did you create the release?
why?
When I build my multi-distro project the tool tries to check out the respective branches. As soon as the previous branch has contained a certain DITAA diagram it will fail because it warns about overwriting the changed diagram png.
CHANGING TO BRANCH '5.4.1'
Error: Could not generate docs:
Git::GitExecuteError: git '--git-dir=/home/jenkins/workspace/hiro_documentation-test/label/asciidoc-buildserver/hirodocs/.git' '--work-tree=/home/jenkins/workspace/hiro_documentation-test/label/asciidoc-buildserver/hirodocs' checkout '5.4.1' 2>&1:error: Your local changes to the following files would be overwritten by checkout:
install-config/cluster/images/ha_single_site.png
Please, commit your changes or stash them before you can switch branches.
Aborting at
/var/lib/gems/2.3.0/gems/git-1.3.0/lib/git/lib.rb:937:in `command'
/var/lib/gems/2.3.0/gems/git-1.3.0/lib/git/lib.rb:644:in `checkout'
/var/lib/gems/2.3.0/gems/git-1.3.0/lib/git/base.rb:306:in `checkout'
/var/lib/gems/2.3.0/gems/git-1.3.0/lib/git/branch.rb:28:in `checkout'
/var/lib/gems/2.3.0/gems/ascii_binder-0.1.9/lib/ascii_binder/helpers.rb:111:in `git_checkout'
/var/lib/gems/2.3.0/gems/ascii_binder-0.1.9/lib/ascii_binder/helpers.rb:555:in `block in generate_docs'
/var/lib/gems/2.3.0/gems/ascii_binder-0.1.9/lib/ascii_binder/helpers.rb:546:in `each'
/var/lib/gems/2.3.0/gems/ascii_binder-0.1.9/lib/ascii_binder/helpers.rb:546:in `generate_docs'
/var/lib/gems/2.3.0/gems/ascii_binder-0.1.9/bin/asciibinder:15:in `call_generate'
/var/lib/gems/2.3.0/gems/ascii_binder-0.1.9/bin/asciibinder:296:in `<top (required)>'
/usr/local/bin/asciibinder:23:in `load'
/usr/local/bin/asciibinder:23:in `<main>'.
I have added the respective .png file to gitignore in all branches but it still won't work.
Any ideas?
Similar to the -d / --distro option, add a -b / --branch option to specify only building given branches. This would enable speedier local testing.
Personally, I'd probably also prefer if a vanilla asciibinder build defaulted to building all distros for only the current working branch (all pages), though I'm not sure whether that would require altering of any of the docs.openshift.* site build jobs as a result. If implemented, possibly also a --all-branches to mimic the current default behavior? If not implemented, then maybe instead a flag to indicate "just build the current working branch, all pages, all distros".
We need to add a basic testing framework to the AsciiBinder codebase so that we can work towards automated testing of pull requests.
During migration to the AsciiBinder framework in our project, I stumbled over a few conceptional issues especially when you having docs as part of the source code and you want to release docs along with the software itself and we treat docs the same as the code.
If you want to build the docs, you have to describe the branch in the _distro_map.yml file. The repository lives inside a release branch. A quick out of my head suggestion to solve this issue would be, build and package the docs just for the current branch when no branches element exists in the _distro_map.yml and let someone pass a name and dir as an argument of the asciibinder command.
A scenario:
You hit the release button in your CI/CD system. We assume you have a branch which reflects a specific version number of the software and the documentation is part of this branch in the software repository. The CI/CD system does his job and the result is an installable artifact of the software and the documentation for this version is built and packaged and needs to be deployed to a public website. To use AsciiBinder in this scenario, it is required to mangle the _distro_map.yml to build the documentation just for this specific new version of the software.
AsciiBinder requires having release branches. When a software is released, we use version tags and I haven't found a way to use the version tag as version number in AsciiBinder. Currently, in our case the version number is defined within Maven and is passed into the module which builds the documentation with the correct version number. I think this could be solved if it would be possible to pass version and deploy target parameters (what you define in the branches: element in the _distro_map.yml) to the asciibinder binary.
It seems to me I have to misuse AsciiBinder a lot to get it to work in this scenario and it is not built by design for such a use case.
Would be Interested about the opinion from maintainer about this scenario.
Thank you in advance
Much like the handling of images, AsciiDoctor forces an unexpected (at least by me) file management thought process on the user. Why do we do that?
Today, AsciiDoctor roots all file includes at the repository's root directory. For example, if I have this file structure (just docs):
.
├── docs
│ ├── a.adoc
│ ├── b.adoc
│ └── more_docs
│ └── c.adoc
├── global.adoc
If I want the file a.adoc' to include the filesb.adoc,c.adocandglobal.adoc`, I have to write the following:
include::docs/b.adoc[]
include::docs/more_docs/c.adoc[]
include::global.adoc[]
This seems less logical in most cases and you would expect the local directory to be the point of resolution. In other words, I would expect to write:
include::b.adoc[]
include::more_docs/c.adoc[]
include::../global.adoc[]
Using Asciidoctor.load_file would make this instead of first reading in the file to a string and using Asciidoctor.load. See:
https://github.com/redhataccess/ascii_binder/blob/master/lib/ascii_binder/helpers.rb#L765
Why was this decision made?
The path of the current page should be accessible as a variable on all pages and within the site template. This would allow us to add a canonical tag to the site header to indicate the full URL of the page that search engines should index.
For example, in Awestruct I can create the canonical tag using the site.base_url and page.url root object properties as follows:
<link rel="canonical" "<%= "#{site.base_url}/#{page.url}" %>">
With AsciiBinder, I would imagine being able to reference the current page path with a topic_path variable as follows:
<link rel="canonical" "<%= "#{site_url}/#{topic_path}" %>">
The topic_path name feels consistent with other AsciiBinder variable naming conventions.
After create a repo with command
asciibinder create mydocs
the file _templates/page.html.erb includes bootstrap-offcanvas.js in the head, but this script requires jQuery, which is loaded at the end of the body. So there is an js error an offcanvas does not work
The bootstrap-offcanvas.js script should be loaded at the body after the jquery.js
It seems that listen requires a greater dependency than what is provided by SCL.
´´´´
[vagrant@origin asciibinder]$ docker build -t "asciibinder" .
Sending build context to Docker daemon 2.56 kB
Step 1 : FROM centos/ruby-22-centos7
Trying to pull repository docker.io/centos/ruby-22-centos7 ... latest: Pulling from centos/ruby-22-centos7
ed98430befc7: Pull complete
35da6faa16cc: Pull complete
29801532e4fd: Pull complete
f7747a5b1ac6: Pull complete
501ce8c368f7: Pull complete
ebe7f1777e28: Pull complete
458beeb57d87: Pull complete
1789b95af6fb: Pull complete
6b9bdf0afc86: Pull complete
20ec015bfd7c: Pull complete
7b999fdecff9: Pull complete
a85af1e6c1cd: Pull complete
01fc9f79d969: Pull complete
df3fd90b7887: Pull complete
8891572fb52c: Pull complete
195218537ee7: Pull complete
8423591d6c32: Pull complete
208484766f24: Pull complete
41894ab76b91: Pull complete
acc2590dcc90: Pull complete
917224853ffe: Pull complete
0626e5e46eb4: Pull complete
Digest: sha256:f60a507a26420e3889cee6cf43a9db375d58e42b1d0ba4beca9612772074559f
Status: Downloaded newer image for docker.io/centos/ruby-22-centos7:latest
---> 0626e5e46eb4
Step 2 : RUN scl enable rh-ruby22 -- gem install ascii_binder
---> Running in e502a52df126
Successfully installed asciidoctor-1.5.4
Successfully installed asciidoctor-diagram-1.4.0
Successfully installed git-1.3.0
Successfully installed formatador-0.2.5
Successfully installed rb-fsevent-0.9.7
Building native extensions. This could take a while...
ERROR: Error installing ascii_binder:
listen requires Ruby version >= 2.2.3, ~> 2.2.
Successfully installed ffi-1.9.10
Successfully installed rb-inotify-0.9.7
Successfully installed ruby_dep-1.3.1
The command '/bin/sh -c scl enable rh-ruby22 -- gem install ascii_binder' returned a non-zero code: 1
´´´´
[edited with feedback from @indigo423 and @Fryguy]
Structurally, the _topic_map.yml file is a YAML stream (i.e. multiple records). The records are each either topic groups or individual topics. All are assumed to be present in the docs repo that AsciiBinder is processing.
I would like to extend AsciiBinder to support the inclusion of remote AsciiBinder-compliant docs repos as build-time topic groups within a local repo being processed.
In other words, given two repos:
There would be a way within _topic_map.yml to use the contents of my_other_repo as a topic group in my_main_repo.
In order for a user to specify that a remote repo should be included, they will create an entry in _topic_map.yml that is similar to that of a topic group:
Name: Remote Group Name
Dir: remote_group
Distros: foo,bar<1>
URL: <see below>
RemoteDistro: baz<2>
<1> Optional
<2> Optional, but unlike the regular Distros key, this is not a list.
The URL value can follow one of two patterns:
http(s)://hostname(:port)/path/to/archive.[bz|tgz|zip] for archive files orhttp(s)://hostname(:port)/path/to/repo(.git)(@<branch_name>) for git reposAsciiBinder will sort out how to acquire and unpack the remote file based on the URL pattern per above.
Given an entry like this in the topic map, AsciiBinder will behave accordingly:
Assuming we get to this point, the contents of the remote file/repo will be dropped into the current branch of the main repo in the specified landing directory. The topics and topic groups contained in the remote repo's _topic_map.yml file will be treated as subtopics / subgroups of the landing directory.
Here are some common use cases that this will support. For the sake of these examples, I am not mentioning distros. Per my proposed notation above, distro flags can be used to affect the inclusion of remote content (or even remote subcontent) but these examples are easier to follow without the added complication.
I have two repos:
And I want to include the remote_repo content in my main_repo docs. Specifically:
So the _topic_map.yml file in the local_repo v1.1 branch will include a record like this:
Name: Remote Topic Group
Dir: remote_group
URL: https://remote_host/[email protected]
And the topic map in the local repo v1.2 branch will include a record like this:
Name: Remote Topic Group
Dir: remote_group
URL: https://remote_host/[email protected]
But the URLs could just as easily point to archives (tgz/zip/bz) as long as each archive URL corresponded to the right versions of the remote_repo content.
Slightly different scenario:
And in this case, both branches would have an identical topic map entry:
Name: Remote Topic Group
Dir: remote_group
URL: https://remote_host/repo.git
asciibinder doesn't seem to have exit codes.
If I have extra files, or other warnings, I still get an exit code 0 despite having WARNING printed in the output.
If I am missing a referenced topic file, the program crashes giving me a 255, but not really giving me happiness :)
Asciibinder does not build branches that have not been manually checked out. An error should be emitted when this happens.
We have split our documentation into two separate branches and want to build a specific one with a jenkins job. We get this error at the end of the build which completes successfully nonetheless.
Can you help me debug the problem here? I have attached the document that apparently throws the error. (Renamed from .adoc because of GitHub upload policy)
curl-examples.txt
[...]
- developer/curl-examples
/usr/lib/ruby/2.3.0/uri/generic.rb:1102:in `rescue in merge': both URI are relative (URI::BadURIError)
from /usr/lib/ruby/2.3.0/uri/generic.rb:1099:in `merge'
from /usr/lib/ruby/2.3.0/uri/rfc3986_parser.rb:89:in `each'
from /usr/lib/ruby/2.3.0/uri/rfc3986_parser.rb:89:in `inject'
from /usr/lib/ruby/2.3.0/uri/rfc3986_parser.rb:89:in `join'
from /usr/lib/ruby/2.3.0/uri/common.rb:265:in `join'
from /var/lib/gems/2.3.0/gems/sitemap_generator-5.1.0/lib/sitemap_generator/sitemap_location.rb:85:in `url'
from /var/lib/gems/2.3.0/gems/sitemap_generator-5.1.0/lib/sitemap_generator/builder/sitemap_index_file.rb:143:in `write_first_sitemap'
from /var/lib/gems/2.3.0/gems/sitemap_generator-5.1.0/lib/sitemap_generator/builder/sitemap_index_file.rb:104:in `finalize!'
from /var/lib/gems/2.3.0/gems/sitemap_generator-5.1.0/lib/sitemap_generator/link_set.rb:461:in `finalize_sitemap_index!'
from /var/lib/gems/2.3.0/gems/sitemap_generator-5.1.0/lib/sitemap_generator/link_set.rb:334:in `finalize!'
from /var/lib/gems/2.3.0/gems/sitemap_generator-5.1.0/lib/sitemap_generator/link_set.rb:41:in `create'
from /var/lib/gems/2.3.0/gems/sitemap_generator-5.1.0/lib/sitemap_generator.rb:42:in `method_missing'
from /var/lib/gems/2.3.0/gems/ascii_binder-0.1.4/lib/ascii_binder/helpers.rb:839:in `block (2 levels) in package_docs'
from /var/lib/gems/2.3.0/gems/ascii_binder-0.1.4/lib/ascii_binder/helpers.rb:806:in `each'
from /var/lib/gems/2.3.0/gems/ascii_binder-0.1.4/lib/ascii_binder/helpers.rb:806:in `block in package_docs'
from /var/lib/gems/2.3.0/gems/ascii_binder-0.1.4/lib/ascii_binder/helpers.rb:804:in `each'
from /var/lib/gems/2.3.0/gems/ascii_binder-0.1.4/lib/ascii_binder/helpers.rb:804:in `package_docs'
from /var/lib/gems/2.3.0/gems/ascii_binder-0.1.4/bin/asciibinder:296:in `<top (required)>'
from /usr/local/bin/asciibinder:23:in `load'
from /usr/local/bin/asciibinder:23:in `<main>'
All builds completed.
In the manageiq_docs repo, I've created a simple test suite that just runs asciibinder build. See ManageIQ/manageiq-documentation#61. I have this running via Travis so that when doc writers make a PR to update the docs, it should fail if they do something wrong. However, I can't figure out how asciibinder build would ever fail.
I'm thinking that maybe there could be an asciibinder check command or perhaps asciibinder build --check that would fail and exit 1 if some conditions aren't met. The only thing I can think of offhand are the current WARNING messages about not updating the _topic_map.yml could instead raise exceptions in this mode. @nhr perhaps you or the openshift-docs team can think of more things?
To maintain revision histories, we need to correlate a change in a specific file with its public id (i.e., the 2-tuple HEADER-LINE, SPECIFIC-ID). It would be nice if Asciibinder could dump out the document's structure in a machine-readable format. Something similar in content to:
$ find . -name '*.adoc' | xargs grep -E -nH -e '(^=+ )|(^\[\[.+\]\])'
./rest_api/revhistory_rest_api.adoc:1:= Revision History: REST API Reference
./rest_api/openshift_v1.adoc:1:= OpenShift v1 REST API
./rest_api/openshift_v1.adoc:12:== Overview
./rest_api/openshift_v1.adoc:15:=== Version information
./rest_api/openshift_v1.adoc:18:=== URI scheme
[...]
./whats_new/ose_3_0_release_notes.adoc:1:= OpenShift Enterprise 3.0 Release Notes
./whats_new/ose_3_0_release_notes.adoc:13:== Overview
./whats_new/ose_3_0_release_notes.adoc:28:== New Features
./whats_new/ose_3_0_release_notes.adoc:53:== Installing OpenShift Enterprise 3.0
./whats_new/ose_3_0_release_notes.adoc:58:== Migrating Applications to OpenShift Enterprise 3.0
./whats_new/ose_3_0_release_notes.adoc:63:[[technology-preview]]
./whats_new/ose_3_0_release_notes.adoc:64:== Technology Preview Features
./whats_new/ose_3_0_release_notes.adoc:92:== Known Issues
./whats_new/ose_3_0_release_notes.adoc:101:== xPaaS Images
./whats_new/ose_3_0_release_notes.adoc:111:=== xPaaS Image for Red Hat JBoss EAP
./whats_new/ose_3_0_release_notes.adoc:128:[[jboss-eap-6.4-v1.1.0]]
[...]
but in proper order (as specified by _build_cfg.yml) and respecting the conditionals (i.e., ifdef:: directives). Actually, whether the default output format is machine-readable or human-friendly is unimportant; it's enough to provide an option to select the preferred format. If you're at a loss for a name for this command, i suggest dump-structure.
How can I add custom fonts to the packaged documents? I need to package my stuff for deployment in locations that are not connected to the internet for security reasons but want to preserve the Corporate Identity. Can I somehow create a _fonts directory that will automatically be copied over?
Presently AsciiBinder supports a single page template folder _templates in a docs repo. This is not as flexible as it could be for handling different page layouts on a per-site basis.
What I would like to propose is this:
Under the _templates directory, there should be one or more per-site directories. One of these must be called default, and this directory is the template directory used by all sites by default. However, other directories may exist in the _templates directory. If these directory names correspond to a site: value in _distro_map.yml, then AsciiBinder will use the templates in that directory to render the topics and topic groups for that site.
In order to support currently established docs repos, this enhancement must be backward compatible.
Therefore:
_templates directory with no child directories is handled exactly like _templates/default under the new behavior. This supports the existing cases._templates directory with one or more child directories will:
_templates directory itselfdefaultThis enhancement will make it much easier to support docs repos that are used as the source for more than two distinct websites.
Similar to asciibinder init, except this function takes an existing remote git repository as an argument. The full functionality is:
_distro_cfg.yml file in the cloned repo and attempt to create tracking branches for all of the distro branches.If you try and set an ID on the header (which is the initial title when included), then the ID gets rendered instead of the title. eg:
[[my-section]]
= My Section Title
The first line in a file is rendered as the title, this means that you cannot set an ID to use in an xref and therefore you cannot link to that without using the title in the xref or linking to the output format filename, which makes it impossible to use in included (include::) or pretty much outside AsciiBinder. This looks to be caused by the following line in helpers.rb, because it assuming the title will always be on the first line.
article_title = file_lines[0].gsub(/^\=\s+/, '').gsub(/\s+$/, '').gsub(/\{product-title\}/, distro_config["name"]).gsub(/\{product-version\}/, branch_config["name"])
This is incorrect as it might have the ID, front matter[1] or other items that make it so the title isn't on the first line. So it should instead either get the title in some other fashion, or search for it. Just as a reminder titles can be defined in different ways in AsciiDoc, eg:
= My Title
My Title
========
or even markdown style headings (this is AsciiDoctor specific though)
# My Title
[1] http://asciidoctor.org/docs/user-manual/#static-website-generators
AsciiBinder requires to be his own git repository. In our project the documentation is versioned and released with the source code. Asciibinder should be able to use the git branches from the project source repository while the documentation is just a subdirectory of it.
Using asciibinder in the following directory structure gives an
.
├── .git
├── README.adoc
├── doc
│ └── mydoc.adoc
└── src
When you run asciibinder in the doc directory does not work and gives an error message, the doc directory is not an asciibinder repository.
We're using asciibinder with jenkins. I've lately updated to version 0.1.9 as per rubygems repo and since then ascii_binder seems to ignore the checked out branch and always builds from develop. We now have to force checkout into a single branch to get the correct contents to build.
I can't find an official release on the repo here so I can't check changes. Was there anything changed about the logic how branches are built? We wanto to build 4 branches all correctly specified in the _distro_map.yml but for some reason this won't work anymore.
We always get the contents of develop as a result in the branch named folders in _package.
possibly also allow an upstream git repo to add as a remote
After making some CSS tweaks (openshift/openshift-docs#3702), I noticed the hard-coded syntax highlighting from CodeRay doesn't look great on a darker codeblock background color:
It would be nice if there were more source-highlighter options available in AsciiBinder, for example being able to:
source-highlighter completelysource-highlighter is disabled (it looks like this is what docs on the Red Hat Customer Portal might be using).this fails:
ascii_binder:
name: Fedora Documentation
author: Fedora Documentation Project <[email protected]>
site: main
site_name: Home
site_url: https://docs.fedoraproject.org/
branches:
f26-en-US:
name: 26
dir: 26
Low priority
I tried to add images in a folder not named "images" and I referenced it according to the Asciidoctor guidelines but in the output the images can not be found. My structure looks somewhat like this:
folder-img:
image.png
image2.png
document.adoc
The document has:
= Title
:toc:
:imagesdir: folder-img
<<<
== Introduction
Some text
image:{imagesdir}/image.png
In Asciidoc preview this works but not in Asciibinder output.
As AsciiBinder has evolved, the function of _build_cfg.yml has evolved as well. At this point, the name is not particularly helpful in communicating what the purpose of the file is. "_topic_map.yml" would be more consistent with "_distro_map.yml" and would help to illustrate how those two files differ but interrelate.
@Fryguy - thoughts?
If you have topic files located in a symlinked directory you get a warning of non-existant topics, even if there are none.
Reproduction Instructions.
$ asciibinder create bar
$ cd bar
$ ln -s welcome welcome_link
<edit topic_map.yml to reference welcome_link>
$ asciibinder build
When rendering a valid yaml, some pieces get rendered in way suggesting invalid syntax.
Take for example this piece of code:
apiVersion: "v1"
kind: "LimitRange"
metadata:
name: "openshift-resource-limits"
spec:
limits:
- type: openshift.io/Image
max:
storage: 1Gi <1>
- type: openshift.io/ImageStream
max:
openshift.io/image-tags: 20 <2>
openshift.io/images: 30 <3>The first line of each array item (prefixed with a dash) gets rendered in red:
If I change the code above like this:
apiVersion: v1
kind: LimitRange
metadata:
name: openshift-resource-limits
spec:
limits:
-
type: openshift.io/Image
max:
storage: 1Gi <1>
-
type: openshift.io/ImageStream
max:
openshift.io/image-tags: 20 <2>
openshift.io/images: 30 <3>The output gets rendered in expected way:
Can we have nice rendering in both cases?
It would be great if ascii_binder supported epub format. I'd love to read docs on my reader :)
I just installed 0.1.10.1 and the new distro parser gives an error
- Distro ID 'hiro-5.4' is not a valid string when a period is present in the distro id.
The _distro_map.yml looks like this:
---
hiro-online:
name: HIRO
author: HIRO Team
site: main
site_name: HIRO Documentation
site_url: http://docs.hiro.arago.co/
branches:
develop:
name: develop
dir: develop
hiro-5.4:
name: HIRO
author: HIRO Team
site: offline
site_name: HIRO 5.4 Documentation
site_url: http://localhost/apps/documentation/
branches:
develop:
name: develop
dir: develop
The second part will not work with the new version. I have to remove the period and it's all fine.
I'm thinking a default to a Create Commons license? The user can always change it if they want.
asciibinder seems to be a sitebuilder/docbuilder combination. If your docs are spread out across multiple repos, we should provide guidance on how to build the documentation site.
I don't see a clear path forward because the generated files contain the breadcrumbs and navigation. Therefore if I generate a bunch of packages and copy them to the same place, I don't get full navigation.
One idea would be to add a git branch change hook to asciibinder. This would allow a custom script to get called everytime asciibinder changed branches. My custom script could clone a bunch of repositories into the current directory and checkout the proper branches. It could then generate a full _topic_map.yml file. After this control could return to asciibinder which wouldn't know it was operating on material not actually in git.
Is there an easier way I am not thinking of?
The nav toggle doesn't work at all, even on the project site http://www.asciibinder.org/latest/welcome/
I would like to have support for syntax like Distros: <major_product>* in the _build_cfg.yml. This would allow me to include major product families using shorter syntax instead of including a huge list of distros just to exclude another product family.
My use case involves two things:
A need to maintain a large set of text replacements (attributes in AsciiDoc or entities in DocBook) that I keep in a separate file. There is one copy per version/branch.
The need to share my repository with a downstream contributor who needs to be able to reorganize the files when they publish their version.
The second point makes it harder for me to just include::entities.adoc[] with proper pathing (see #60 ) in every file.
Would we be willing to add an Entity declaration to the _topic_map.yml? I see it operating like this:
---
Name: AsciiBinder Doc Project
Dir: welcome
Entity: global
Topics:
- Name: Welcome
File: index
- Name: Bar
File: bar
- Name: Topic
Dir: topic
Entity: ent
Topics:
- Name: Foo
File: foo
The file global.adoc is loaded and prepended to all files in the entire "AsciiBinder Doc Project". This way any entities in this file are available to all asciidoc pages. The file ent.adoc is loaded and prepended only for files in the "Topic" topic set.
global.adoc lives in the welcome/ directory.
ent.adoc lives in the welcome/topic/ directory.
No include directives are required. This functionality would be optional.
This would allow for improved organization of topics and be able to expand/retract topics while looking at 3rd level topics. So supporting both File or Dir at a 3rd level should do the trick.
So the _build_cfg.yml would support the following structure:
Name: REST API
Dir: api
Topics:
- Name: Examples
Dir: examples
Topics:
- Name: Querying Examples
File: queries
- Name: Services
Dir: services
Topics:
- Name: Ordering Services
File: ordering_services
- Name: Retiring Services
File: retiring_services
- Name: Automation Requests
File: automation_requests
Hi AsciiBinder hackers,
On the philosophy page, there is the sentence: "AsciiBinder takes advantage of git pull requests as a means of refining content before it becomes part of the docs, ...".
What does that mean, precisely? Is there any actual integration with GitHub?
Note that the changelog concept is under active discussion and so this is currently just an advisory issue.
This is a two-part proposal. Part one is for a changelog format that provides a history of topic file moves / renames / deletes within a single repo. Part two is for additional AsciiBinder features that would make it easy for writers to move / rename / delete topics and have AsciiBinder automatically modify the _build_cfg.yml and _changelog files accordingly.
The two primary benefits of change tracking are as follows:
Scenario: a topic at path “coolconcept/explanation.adoc” gets renamed to “coolconcept/user_guide.adoc” and later is reorganized under “howtos/“. At some point after that, the file gets split up into new topics and the original file is deleted entirely.
Here’s what the changelog file might look like:
2014-01-01 coolconcept/explanation.adoc => coolconcept/user_guide.adoc
2015-08-25 coolconcept/user_guide.adoc => howtos/user_guide.adoc
2016-02-17 howtos/user_guide.adoc => [deleted]
The general form is:
YYYY-MM-DD <original_topic_group>/<topic_filename> => <new_topic_group>/<topic_filename>
The special token [deleted] can be used in place of a new group/topic path when a file is removed.
In following the pattern of metadata naming in AsciiBinder repos, this file would be called _changelog.
Over the lifespan of a docs repo, the changelog file runs the risk of getting very large. Currently a pruning delta of one year seems reasonable. In other words, as the oldest changes in the file exceed a year in age, they could be removed from the changelog.
AsciiBinder can be extended with a few new functions to simplify the use of the changelog.
This function would do the following things on behalf of the user:
git mv the topic file_changelog file_build_cfg.yml fileSimilar to move-topic this would:
git rm the topic file_changelog file_build_cfg.yml fileThis function already exists, but based on the presence of the _changelog file it could generate a set of redirect rules suitable for use in Apache or NGINX.
When trying to use images in AsciiBinder without embedding them via the :data-uri: attribute, images don't work as soon as you move them to another host. I had a bit of a look into it and the cause looked to be because of:
Related: openshift/openshift-docs#2134
First, not sure if it's styling choice or not, for document menus, when expanding topic groups and such, there are no icons like > to expand and ^ to contract the topic menus.
Second, the admonition icons (info, warning, etc.) seem to be missing, I get the blue square instead.
I get a bunch of messages like these in my build log:
asciidoctor: WARNING: <stdin>: line 5: section title out of sequence: expected level 1, got level 2
Unfortunately asciibinder does not mention which file is being processed so I can not find out which file has these problems. Can you improve the logging behavior so I get a chance to review the documents?
Thanks
We need a way to validate links, at the very least for catching normal link typos during a local build. This could be either in asciibinder itself, or maybe implemented in asciidoctor upstream?
Also, currently whenever a topic changes location, the writer must manually search and update any affected links. It would be nice if asciibinder had a way to "move" a topic for you, such that it also just updated any links automatically.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.