I am using Sphinx to generate HTML documentation and have a structure similar to the following:
docs/
├── _static/
├── _templates/
├── guide/
│ ├── index.rst
│ └── image.jpg
├── conf.py
├── index.rst
├── make.bat
└── Makefile
I reference docs/guide/index.rst from docs/index.rst and embed docs/guide/image.jpg in docs/guide/index.rst using the image: directive.
What I notice is that after running make html, the build directory created has duplicated image.jpg, once in a build/html/_static/ folder, and once in a build/html/_images/ folder. Is there any reason for this or way to not duplicate the image? It seems that the generated HTML is only referencing the image using the build/html/_images/ path.
Related
I am a relative beginner developing a Python package. At the root of the repository there are two important directories: images and docs. The former contains some png and svg files I would like to put inside a documentation, the latter is where I run sphinx-quickstart in. I cannot change that layout therefore I have to let Sphinx know to use the top-level images directory while building the docs.
According to what I found over the internet I adjusted the conf.py file to have:
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static', '../images']
And in the index.rst I have to point to the image file itself:
.. image:: ../images/scheme.svg
:width: 500
:alt: schematic
:align: center
Having these two set up I run make html and I do get clean logs but the output directory is a little strange... Once the build is finished i have a docs/_build/html directory which contains _static and _images sub-directories (among many others). What I find strange is that inside docs/_build/html/_static I see all the contents of the root-level images being copied over whereas (at the same time) inside docs/_build/html/_images I only have scheme.svg. So essentially this one file is duplicated into these two subdirectories...
This does not look very clean to me... how should I adjust this setup?
Reply to the comment of bad_coder:
Below I will paste a tree with the dir structure (kept only the relevant elements):
.
├── docs
│ ├── Makefile
│ ├── _build
│ │ └── html
│ │ ├── _images
│ │ │ └── scheme.svg
│ │ ├── _static
│ │ │ ├── scheme.svg
│ ├── conf.py
│ ├── index.html
│ ├── index.rst
├── images
│ ├── scheme.svg
I am using the pandoc/latex docker container and having some issues with --resource-path. My project is using a latex template which references an image, and I cannot get latex to find the image.
My file tree looks like this:
/app/tmp/
├── 42
│ ├── galley.md
│ └── img
│ ├── 1.jpg
│ ├── 5.jpg
│ ├── 7.jpg
│ └── 9.jpg
And I have user data dirs like this:
/home/worker/.pandoc
├── assets
│ └── logo.png
└── templates
└── sow.latex
The command I'm using looks like
pandoc --from markdown --to latex /app/tmp/42/galley.md --output=/app/tmp/42/2/out.pdf --template sow.latex --resource-path=.:/home/worker/.pandoc/assets
As mentioned the latex template does make a reference to logo.png:
\includegraphics[width=0.75\textwidth]{logo.png}\par\vspace{1cm}
Whenever I run pandoc I get the following error:
! Package pdftex.def Error: File `logo.png' not found: using draft setting.
If I comment out the reference to logo.png then everything works fine including the other images referenced within galley.md. Likewise if I copy logo.png into the directory with galley.md everything works fine; as a workaround that is fine, but it feels quite clangy so I would rather sort out how to reference logo.png from where it sits in assets.
Is there something I've missed about how reference-path plays with template?
This happens locally via sphinx running readthedocs theme, it also happens in readthedocs.io.
I have added an svg logo (actually it's just the downloaded rtd logo.svg copied from their site for testing).
I've added the settings to conf.py and html builds fine.
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_logo = 'logo.svg'
html_theme_options = {
'logo_only': True,
'display_version': False,
}
If I inspect the logo class in Firefox it is set to "auto", if I add a width in px, the logo appears.
I feel as if I am missing something about the configuration of the readthedocs theme in the conf.py file?
Surely I should not have to hack at the CSS manually: I see no indication of altered CSS in the Readthedocs.io site when looking at their source.
I'm looking for an elegant solution - I do not want updates to readthedocs theme to break my site because I have been overriding the theme's CSS.
You're doing correctly
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_logo = "mepro_headshot.png"
html_theme_options = {
'logo_only': True,
'display_version': False,
}
I just added the logo in my docs/source/ and when you run make html, it copies your pngor svg files into docs/html/_static/. As mentioned in the documentation: New in version 0.4.1: The image file will be copied to the _static directory of the output HTML, but only if the file does not already exist there.
├── docs
│ │ └── html
│ │ ├── _static
│ │ │ ├── mepro_headshot.png
│ │ │ ├── mepro_headshot.svg
│ └── source
│ ├── _images
│ ├── _static
│ ├── _templates
│ ├── conf.py
│ ├── index.rst
│ ├── mepro_headshot.png
│ ├── mepro_headshot.svg
and it seems both
svg
and
png works
I had a similar issue, I've resolved it by adding the _static directory at the html_logo parameter.
html_theme = 'alabaster'
html_static_path = ['_static']
html_logo = "_static/logo_rw.png"
Same problem with .svg width auto zero px. For anyone that does want to set the css here is a solution:
sphinx-rtd-theme v0.5.0, sphinx v3.4.3
docs/_build/html/_static/css/custom.css:
/*
`width:auto` was rendering 0px wide for .svg files
https://stackoverflow.com/questions/59215996/how-to-add-a-logo-to-my-readthedocs-logo-rendering-at-0px-wide
*/
.wy-side-nav-search .wy-dropdown > a img.logo, .wy-side-nav-search > a img.logo {
width: 275px;
}
I have some confusion regarding Golang directory structure.
Base on the book The Way to Go by Ivo Balbaert, project code should be placed into src, and recommends the following directory structure.
├──src/
| ├──main.go
| ├──say/
| | ├──say.go
| | ├──say_test.go
├──bin/
| ├──say
└──pkg/
└──linux_amd64/
└──say.a
but I found that many packages in github.com, have no src directory.
For example:
https://github.com/facebookgo/grace
https://github.com/astaxie/beego
So, I don't know whether src directory is needed.
I have some project, their have inter-dependency.
They are managed in a private GitLab repository.
How can I organized them?
This article by Ben Johnson has guided me on this when I was starting with Go.
It's generally good to start with something like this (assuming you are inside your project directory like $GOPATH/src/myproject:
├──cmd/ -- this is where you compose several packages in to main package
| ├──foo -- an example would be `foo`
| | ├──main.go
├──pkg/ -- this is where put your reusable packages
| ├──pkg1 -- reusable package 1
| ├──pkg2 -- reusable package 2
├──otherpackage1
| ├── ...
├──otherpackage2
| ├── ...
You can have a look at this example from go-kit for this kind of project structure.
Sometimes it will depend on your needs. On our workflow, we are using a hot code reload tool called fresh, so we needed to put the main.go on the project root so that the tool can detect all the file changes and rebuild the source code.
├──app/
| ├──app.go
├──model/ --
| ├──model.go
├──store
| ├──store.go
├──main.go -- this is where the app starts
├──...
On the app.go package, I have something like func Run() error which starts the application. On the main.go, I am just calling the function:
...
func main(){
log.Fatal(app.Run())
}
Now there are new ways to organize Go projects.
The GitHub golang-standards repository says:
This is a basic layout for Go application projects. It represents the
most common directory structure with a number of small enhancements
along with several supporting directories common to any real world
application.
This project layout is intentionally generic and it doesn't try to
impose a specific Go package structure.
Or you can follow this slides:
$GOPATH/
src/
github.com/user/repo/
mypkg/
mysrc1.go
mysrc2.go
cmd/mycmd/
main.go
bin/
mycmd
Here is another project layout sample Simple Go project layout with modules
├── LICENSE
├── README.md
├── config.go
├── go.mod
├── go.sum
├── clientlib
│ ├── lib.go
│ └── lib_test.go
├── cmd
│ ├── modlib-client
│ │ └── main.go
│ └── modlib-server
│ └── main.go
├── internal
│ └── auth
│ ├── auth.go
│ └── auth_test.go
└── serverlib
└── lib.go
Some answer points out the go standard layout, however, there is one issue this is not a standard Go project layout by Russ Cox
There are two problems with this GitHub repo:
it claims to host Go standards and does not, in the sense that these are in no way official standards
the project-layout standard it puts forth is far too complex and not a standard
Regarding "why not tell us the standard Go project layout and we'll update the doc?", that only addresses point 2. If there really were standards, they would be in the main Go project doc tree. The standard for project layout would also be a lot shorter. I appreciate your trying to provide a useful resource, but calling it 'golang-standards' is claiming more than it is.
But for the record, the minimal standard layout for an importable Go repo is really:
Put a LICENSE file in your root
Put a go.mod file in your root
Put Go code in your repo, in the root or organized into a directory tree as you see fit
That's it. That's the "standard".
Update at 11/30/2021
Here are a summary from How to structure Go code
Before we start
doc.go file puts the general description of the package
Readme file a general overview of this project
When you have more documentation to provide put them into the docs folder
For linting use golangci-lint. Enable all linters that seem to be reasonable for your project
The flat structure (single package)
courses/
main.go
server.go
user_profile.go
lesson.go
course.go
When to create a new package?
When you have more than one way of starting your application
When you want to extract more detailed implementation
When you started to add a common prefix to closely related things
Modularisation
Organising by kind
.
├── handlers
│ ├── course.go
│ ├── lecture.go
│ ├── profile.go
│ └── user.go
├── main.go
├── models
│ ├── course.go
│ ├── lecture.go
│ └── user.go
├── repositories
│ ├── course.go
│ ├── lecture.go
│ └── user.go
├── services
│ ├── course.go
│ └── user.go
└── utils
└── stings.go
Organising by components
.
├── course
│ ├── httphandler.go
│ ├── model.go
│ ├── repository.go
│ └── service.go
├── main.go
└── profile
├── httphandler.go
├── model.go
├── repository.go
└── service.go
Clean Architecture
You have 4 layers of your application or module (depending on how big your codebase is): Domain, Application, Ports, Adapters. In some sources, names may differ.
The src directory is not needed and in fact a lot of public repositories do not use this structure.
There is a few different way of organizing your project. If you plan on having your project used by an other repository, like lib. I would recommend using a cmd struct something like this. This would also be the recommended way of doing it if there would be more then one way of starting the application. (multipliable main.go files)
├──cmd/
| ├──(application name)
| | ├──main.go
└──say/
├──say.go
└──say_test.go
Otherwise for example if it is a standalone application. You can place the main.go in the root of the repository.
bin and pkg you can keep in the root and add this to .gitignore. (assuming you are using git)
The book describes the directory structure after checkout. It would have been helpful if the book included the .git directory.
$GOPATH/src is required for imports to work.
├──src/
| ├──.git
| | ├──...
| ├──main.go
| ├──say/
| | ├──say.go
| | ├──say_test.go
├──bin/
| ├──say
└──pkg/
└──linux_amd64/
└──say.a
In practice, main.go would actually be in a path that reflects the remote git repository, for instance
.
├── bin
│ └── say
├── pkg
│ └── linux_amd64
│ └── github.com
│ └── pschultz
│ └── hello-world
│ └── say.a
└── src
└── github.com
└── pschultz
└── hello-world
├── .git
│ └── ...
├── main.go
└── say
├── say.go
└── say_test.go
I have a beego project in IdeaProject. The structure is like this:
MathApp
├── conf
│ └── app.conf
├── main.go
├── main_test.go
└── views
├── invalid-route.html
└── result.html
However, it shows the error can't find templatefile in the path:views/result.html. I have set the gopath as C:/gopath.
Any suggestion?
You can see the code producing this error in template.go
This issue mentions:
Please use the bee run, as go get install the binary into the gopath/bin, while the static file still in the gopath/src/myproject.