# Documenting packages

**URL:** <https://discourse.julialang.org/t/documenting-packages/94493>\
**Category:** General Usage\
**Tags:** question\
**Created:** [February 12, 2023, 6:17am UTC](https://discourse.julialang.org/t/documenting-packages/94493 "2023-02-12T06:17:31Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![dscolby](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dscolby/32/204483_2.png) [@dscolby](https://discourse.julialang.org/u/dscolby)\
**Post date:** [February 12, 2023, 6:17am UTC](https://discourse.julialang.org/t/documenting-packages/94493/1 "2023-02-12T06:17:31Z")

</div>

I just created a new package but I’m having a lot of trouble getting the documentation to render with Documenter.jl. When I deploy it to GitHub pages it displays the readme instead of the index.md file in my docs/src directory and it only seems to be displaying raw html without the CSS elements. It also seems that the @autodocs macro isn’t working. I have an api.md file formatted as follows but the html page writes exactly what is in api.md instead of actually documenting the modules.

````julia
# API

```@autodocs
modules = [CausalELM, Estimators, Metalearners, Models, ActivationFunctions, Metrics, 
    CrossValidation]

````

```julia

Any help would be much appreciated.
```

---

<div class="post-metadata">

**Author:** ![jling](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jling/32/212909_2.png) [@jling](https://discourse.julialang.org/u/jling)\
**Post date:** [February 12, 2023, 6:18am UTC](https://discourse.julialang.org/t/documenting-packages/94493/2 "2023-02-12T06:18:21Z")

</div>

you need to show us the repo so we can see what you did wrong

---

<div class="post-metadata">

**Author:** ![dscolby](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dscolby/32/204483_2.png) [@dscolby](https://discourse.julialang.org/u/dscolby)\
**Post date:** [February 12, 2023, 6:29am UTC](https://discourse.julialang.org/t/documenting-packages/94493/3 "2023-02-12T06:29:12Z")

</div>

Sorry, I thought I included that. The repo is [here](https://github.com/dscolby/CausalELM.jl).

---

<div class="post-metadata">

**Author:** ![jling](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jling/32/212909_2.png) [@jling](https://discourse.julialang.org/u/jling)\
**Post date:** [February 12, 2023, 6:31am UTC](https://discourse.julialang.org/t/documenting-packages/94493/4 "2023-02-12T06:31:47Z")

</div>

> <https://github.com/dscolby/CausalELM.jl/blob/4294ef2b4f3d09e96969553d11ec778b56f01182/docs/make.jl#L15-L20>

you’re not deploying the docs at all.

You’re not supposed to track the `docs/build` directory in your main branch. And at the moment the `gh-pages` branch is a copy of your main branch instead of being a doc branch

Here’s a good example:

> <https://github.com/JuliaData/CSV.jl/blob/main/docs/make.jl>

---

<div class="post-metadata">

**Author:** ![dscolby](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dscolby/32/204483_2.png) [@dscolby](https://discourse.julialang.org/u/dscolby)\
**Post date:** [February 12, 2023, 7:54am UTC](https://discourse.julialang.org/t/documenting-packages/94493/5 "2023-02-12T07:54:35Z")

</div>

I uncommented and fixed the deploydocs block but it still isn’t finding the right files.

---

<div class="post-metadata">

**Author:** ![jmair](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jmair/32/35117_2.png) [@jmair](https://discourse.julialang.org/u/jmair)\
**Post date:** [February 12, 2023, 8:15am UTC](https://discourse.julialang.org/t/documenting-packages/94493/6 "2023-02-12T08:15:45Z")

</div>

I would recommend using the plugin from `PkgTemplates.jl` to setup a GitHub action to build and deploy the docs for you, as it does all the hard work. Even if you have already created your project, you can grab the workflow easily enough.

You just need a `.yml` file in `.github/workflows`. An example one is here - [Experimenter.jl/CI.yml at main · JamieMair/Experimenter.jl · GitHub](https://github.com/JamieMair/Experimenter.jl/blob/main/.github/workflows/CI.yml).

You can remove the block for testing and just use the documentation one if you like, this should deploy the docs on every commit to main.

EDIT: It seems you already have a `CI.yml` file, you can just add the documentation task from the link above and it should handle the docs for you, just like the testing.

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [February 12, 2023, 10:30am UTC](https://discourse.julialang.org/t/documenting-packages/94493/7 "2023-02-12T10:30:54Z")

</div>

I would also recommend deleting the `docs/build` from git and adding it to the gitignore.

It illustrates that the run locally seems to run at least, though I can not see where it would have generated a `api.html` file, is that maybe even an outdated run of the docs in `build/` (one reason more to delete it 😉 ) ?

---

<div class="post-metadata">

**Author:** ![jling](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jling/32/212909_2.png) [@jling](https://discourse.julialang.org/u/jling)\
**Post date:** [February 12, 2023, 3:14pm UTC](https://discourse.julialang.org/t/documenting-packages/94493/8 "2023-02-12T15:14:42Z")

</div>

> **[GitHub - dscolby/CausalELM.jl at gh-pages](https://github.com/dscolby/CausalELM.jl/tree/gh-pages)**
>
> gh-pages

if you look at this branch, it’s still just a copy of your main branch, this is wrong.

you may try delete this branch all together and try re-trigger the CI

---

<div class="post-metadata">

**Author:** ![dscolby](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dscolby/32/204483_2.png) [@dscolby](https://discourse.julialang.org/u/dscolby)\
**Post date:** [February 13, 2023, 12:14am UTC](https://discourse.julialang.org/t/documenting-packages/94493/9 "2023-02-13T00:14:59Z")

</div>

Thank you all for looking at my repo. I ended up creating a new package structure with PkgTemplates as @jmair suggested. I also realized that I was using docs/build instead of root for my gh-pages deployment and changing that fixed the problem after I created the new package structure.