Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Meta] Migration tooling bugs #160

Open
11 of 12 tasks
bmorelli25 opened this issue Jan 10, 2025 · 6 comments
Open
11 of 12 tasks

[Meta] Migration tooling bugs #160

bmorelli25 opened this issue Jan 10, 2025 · 6 comments
Assignees

Comments

@bmorelli25
Copy link
Member

bmorelli25 commented Jan 10, 2025

Migration Tooling Bugs

The following bugs should be prioritized.

Output

Links

  • @siamakp-elastic to convert links to md syntax. An example is below. Note that some links span multiple lines. The newline should be removed in this case:
    https://www.elastic.co/guide/en/apm/agent/java/current/index.html[Elastic APM
    Java agent]
    
    Note: on further examination, it appears that single-line links are converted to MD but that conversion goes wrong in some way and the output is a blank string. See the bullet points here as an example (when converting obs-docs) http://localhost:5000/monitor-k8s-otel-edot.html.

Unicode

The migration tool shouldn't output unicode. I see a lot of examples of this in the zip file: >,  , ’, etc.

Variables

  • @bmorelli25 convert asciidoc vars to yml and avoid var substitution
  • @siamakp-elastic maintain current use of - in variables (currently converts to _)
  • @siamakp-elastic to introduce temporary workaround in migration tooling
  • Variable substitution does not work in navigation_title frontmatter. To be fixed by @elastic/docs-engineering
    Screenshot here Image

Definition lists

We need a solution for this. See #109.

Tabs

  • @bmorelli25 right script that iterates through tabs and converts HTML to MD w/regex
    • script run with: python3 convert.py -dir path/to/dir/
  • @siamakp-elastic attempt to add regex HTML tab to MD functionality to migration tool

Dropdowns

Related to #107.

The migration script currently migrates dropdowns to following syntax:

```{admonition} 'Example 60. *Logs*'
:class: note dropdown

//content
```

We don't support this syntax in docs-builder. The syntax should be:

:::{dropdown} Dropdown Title

//content
:::

Note that an optional :open: parameter is also supported. I'm not sure if your migration tooling is handling the open-by-default dropdowns or not, @siamakp-elastic

Other bugs

Lower priority bugs to look into as time allows.

Table conversion

We should strip the table conversion syntax from:

```{table}
:width: auto
| <header> | <header> | <header> | ... |
| -------- | -------- | -------- | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|   ...    |   ...    |   ...    | ... |
```

to just

| <header> | <header> | <header> | ... |
| -------- | -------- | -------- | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|   ...    |   ...    |   ...    | ... |

Bullet points

When a bullet point only contains a link, it doesn't migrate?
Asciidoc link: https://www.elastic.co/guide/en/observability/current/monitor-k8s-otel-edot.html
MD link: http://localhost:5000/monitor-k8s-otel-edot.html

Screenshot here Image

Code block callouts

We had previously asked @siamakp-elastic to convert code callouts to footnotes. We now support callout syntax in docs-builder. The code callout syntax that we should update adoc-to-md is:

```go
transaction := apm.DefaultTracer().StartTransaction("GET /", "request") <1>
traceContext := transaction.TraceContext() <2>

// Send TraceContext to receiving service
traceparent := apmhttp.FormatTraceparentHeader(traceContext) <3>
tracestate := traceContext.State.String()
```

1. Start a transaction
2. Get `TraceContext` from current Transaction
3. Format the `TraceContext` or `tracestate` as a `traceparent` header.

In other words:

  • A code block can include <\d+> at the end to indicate code callouts.
  • A code block with this style of callouts needs to be followed by an ordered list with an equal amount of items as called out.

Questions for writers during bug bash

  1. We're currently choosing not to support inline admonitions. Provide examples if you think this choice is wrong. See [Discuss] Inline admonitions #108 & Add support for context-specific admonitions #94 (comment) for more info.
  2. We do not currently have syntax to convert definition lists into. What do we need to support here? How can we support this and also be prescriptive about how def lists are used? See [Discuss] Definition lists #109 for more info. Examples of def lists:
This was referenced Jan 10, 2025
@Mpdreamz
Copy link
Member

Do note we do support the open option on all admonitions

```{admonition} 'Example 60. *Logs*'
:open: true/false

//content
```

{dropdown} by itself just creates a collapsible section without any admonition styling.

@Mpdreamz
Copy link
Member

@siamakp-elastic another note is that the output currently generates to docs/source at least the zip I saw. Can we make sure the conversions we put in place just render to docs ?

The docs/source is a leftover from the POC days that we never got round to adjust. Will move the docs here and in the example repos to just /docs as well.

@bmorelli25
Copy link
Member Author

{dropdown} by itself just creates a collapsible section without any admonition styling.

In the asciidoc docs all of our dropdowns are currently unstyled so I think this is the better fit. I'd also be interested in discussing whether or not we should support open in admonitions. If admonitions aim to draw attention to some information, I don't see a use case where they should be collapsed.

@Mpdreamz
Copy link
Member

Ahh that makes sense @bmorelli25 !

I think your argument to not support dropdown in admonitions makes a lot of sense.

Just give me the go-ahead to rip it out :)

@bmorelli25
Copy link
Member Author

Just give me the go-ahead to rip it out :)

Let's do it! 🔨

@bmorelli25
Copy link
Member Author

Related: #179 #178

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants