Question about git documentation

Help & Support
1

Hi, actually I’m focusing more about to document my project and the API.

I would like to ask a question.

I have a pro Git account. I saw a lot of gits projects, like crystal , and others , have an API documentation like that (crystal example: Crystal 1.7.1).

I saw a lot of API documentation like that. So my question is, is there any automated interface or tool with git to generate this documentation, or it’s a full web coded page ?

Because I would like to do an API documentation like this

2

Maybe something like this?

BTW, the forum has a search function if you click the magnifier lens up top.
grafik

3

You just need to run crystal docs in the root of your project.

Refs:

4

Thanks a lot ! Just a last question !

How can I generate the documentation but for multiple versions ? (based on tags or branch). Because for example if you go to the crystal api doc, you can select the version you would like to focus

5

My question isn’t accurate ?

6

You can’t expect to always get an answer. People are busy, they might not know the answer, etc.

Here’s something:

$ crystal docs --help
Usage: crystal docs [options]

Generates API documentation from inline docstrings in all Crystal files inside ./src directory.

Options:
    --project-name=NAME              Set project name
    --project-version=VERSION        Set project version
    --source-refname=REFNAME         Set source refname (e.g. git tag, commit hash)
    --source-url-pattern=REFNAME     Set URL pattern for source code links
    --output=DIR, -o DIR             Set the output directory (default: ./docs)
    --format=FORMAT, -f FORMAT       Set the output format [html, json] (default: html)
    --json-config-url=URL            Set the URL pointing to a config file (used for discovering versions)
    --canonical-base-url=URL         Indicate the preferred URL with rel="canonical" link element
    --sitemap-base-url=URL, -b URL   Set the sitemap base URL and generates sitemap
    --sitemap-priority=PRIO          Set the sitemap priority (default: 1.0)
    --sitemap-changefreq=FREQ        Set the sitemap changefreq (default: never)
    -D FLAG, --define FLAG           Define a compile-time flag
    --error-trace                    Show full error trace
    --no-color                       Disable colored output
    --prelude                        Use given file as prelude
    -s, --stats                      Enable statistics output
    -p, --progress                   Enable progress output
    -t, --time                       Enable execution time output
    -h, --help                       Show this message
    --warnings all|none              Which warnings to detect. (default: all)
    --error-on-warnings              Treat warnings as errors.
    --exclude-warnings <path>        Exclude warnings from path (default: lib)

See this in particular:

 --json-config-url=URL            Set the URL pointing to a config file (used for discovering versions)

That said, I don’t know what’s the format of that JSON so you’ll have to figure that out by looking at Crystal’s source code.

1 Like
7

I’m not sure if it’s documented anywhere but as @asterite said you can use the --json-config-url option when building the docs for this. This file should be structured like https://crystal-lang.org/api/versions.json. It does require some manual work however as you will have to build the docs for the particular version, upload them to wherever you’re hosting the documentation, and be sure to update the versions file. The only thing the dropdown does is essentially just redirect you to the path denoted for each version.

1 Like
8

Oh thank you, now it’s more clear definitely.

If I have any questions I will come back

9

I checked all dirs one by one in the crystal-website repo and the crystal repo, but I can’t find the api documentation git.

Without example, it’s a bit complicate to understand how to generate for multiple versions.

I will continue to investigate

10

To be clear generating for multiple versions is essentially just like:

git checkout v0.1.0
crystal docs

Then upload the docs/ dir as like docs/0.1.0. Then if you release 0.2.0 you’d do:

git checkout v0.2.0
crystal docs

And upload that as docs/0.2.0.

Where each of these directories are hosted on something that can serve static HTML/JS. Then the version dropdown just redirects you to what specific folder should be displayed.

3 Likes