So, developer documentation. We currently use reStructuredText to write the docs, Sphinx for static html generation and Read The Docs for automatic builds from GitHub repo and docs site hosting. But we like Netlify to scale up, add a few features such as role-based access control, and generally build out a developer portal. It would help me greatly if anyone here can help me resolve the following questions before embracing Netlify:
- The Netlify Drop feature is here to stay, right? I mean it’s not going to be demoted during the next 3 to 5 years in the name of some dynamic JAMStack thing…? I really love the Netlify Drop feature where I can just drop the locally generated static html folder and see the site live in a few seconds. This feature is a must-have for us because we do not like to give access to our Python headers to any hosting site. So we will locally build static html and upload it with Drop.
- Are there any plans for Netlify to officially support Sphinx documentation builder? I looked through docs and it doesn’t mention so that means Netlify does not support it. I see someone graciously wrote up how to do it here GitHub - HangarOrg/sphinx-netlify-cicd: Automated deployments of Sphinx documentation to Netlify, but what is Netlify’s position on Sphinx? Supporting in near future? Don’t care? Use the approach described at this link and you don’t care, and if it breaks I am on my own?
- The Drop feature is a must-have, and the Sphinx docs builder feature is a “I am begging you, please” feature, decision-making-wise.
Comments, help, reassurances, showing the door? Help! Thanks! :- )
RK
Hi @rk-statichtml,
-
The Drop feature is nowhere close to deprecation. However, it has its own set of limitations (like you can’t use Netlify Functions) and don’t recommend it especially if the website is going to be huge and/or other options are possible. The recommended go-to option to deploy (when you don’t want to use Git) is using Netlify CLI. We always recommend the CLI for any website that might be huge.
-
I can’t say that we officially support any of the static website builders. It’s because, Netlify will build anything you throw at it as long as it can build within the hardware and software limitations. Consider Netlify as a command line tool. If you have all the necessary dependencies installed, you just need to run a (non-sudo) command and the command will do its job. So, if your code builds fine on Ubuntu, it should build fine on Netlify too. It’s true for all generators. It’s just that, the ones listed on the internet or on Netlify’s pages like documentation, are the ones known to Netlify and used very commonly. This was the first time I personally came across Sphinx. So, to be honest, chances are you’d have to figure out a lot of stuff yourself as there might be a very less percentage of people who are familiar with your stack and would be able to help you.
To summarise, the most official support that we could see here is having a docs page that might mention using Sphinx, but yes that might take some time. I’m not a developer or a decision maker in the team, so I can’t make any promises on behalf of anyone.
But to suggest you something, the best way going forward is using Netlify CLI. You can give Git-based builds a try, but if that doesn’t work, you could build locally and deploy via CLI.
2 Likes
Thanks, @hrishikesh, for the detailed response. I get the picture. What you said in (2) makes sense and your reply also informs me the overall thinking and the approach Netlify is taking. Works for me. I did not even think of Netlify CLI but now I will give it a whirl.
1 Like